Granularity is an essential principle of REST API design. As we understand business functions divided into many small actions are fine-grained, then business functions divided into large operations are coarse-grained. However, discussions about what level of granularity that needs to be in APIs may vary; we will get distinct suggestions and even end up in debates. Regardless, it is best to decide based on business functions and its use cases, as granularity decisions would undoubtedly vary on a case by case basis.

In some cases, calls across the network may be expensive and so, to minimize them a coarse-grained API may be the best fit, as each request from the client forces lot of work at the server side and, in fine-grained APIs, many calls are required to do the same amount of work at the client side.

Consider the following example. A service returns customer orders (say n orders) in a single call; this is a coarse-grained API in action. In case of fine-grained, it returns only the customer IDs, and for each customer ID, the client needs to make an additional request to get details, so n+1 calls need to be made by the clients; these may be expensive round trips regarding its performance and response times over the network.

In a few other cases, APIs should be designed at the lowest practical level of granularity, because combining them is possible and allowed in ways that suit customer needs.

Now, check out this example, an electronic form submission may need to collect an address as well as, say, tax information. In this case, there are two functions one is a collection of the applicant's whereabouts, and another is a collection of tax details. Each task needs to be addressed with distinct API and requires a separate service because an address change is logically a different event and not related to tax time reporting, that is, why one needs to submit the tax information (again) for an address change.

Level of granularity should satisfy the specific needs of the business functions or use cases. While the goal is to minimize the calls across the network and for better performance, understanding the set of operations that API consumers require and how they would give a better idea of the right grained APIs in our designs is important.

Say internal services consumers for those who multiple calls to the API servers are acceptable and those APIs can be designed as fine-grained, and the external consumers and if they need to avoid several round-trips to the API then plan as coarse-grained.

At times it may be appropriate that the API design supports both coarse-grained as well as fine-grained to give the flexibility for the API developers to choose the right APIs for their use cases.

The following points may serve as some basic guidelines for the readers to decide their API granularity levels in their API modelling:

• In general, consider services coarse-grained and APIs fine-grained.
• Maintain a balance between the amount of response data and the number of resources required to provide that data will help to decide the granularity.
• The types of performed operations on the data should also be considered as part of the design when defining the granularity.
• Read requests are normally coarse-grained. Returning all information as required to render the page won't hurt as much as two separate API calls in some cases.
• On the other hand, write requests must be fine-grained. Find out common operations clients need, and provide a specific API for that use case.
• At times, you should use medium-grained, that is, neither fine-grained or coarse-grained. An example could be as seen in the following sample where the nested resources are within two levels deep.

Consider the following snapshot that reflects a medium-grained API response:

Let's conclude this section with a broad guideline that helps to determine the right service granularity—identify the vital business entities that the service impacts and model the life cycles accordingly; that is, there should be only one API operation for one business outcome.

The preceding guideline may lead to a number of API deployment units, and this can cause annoyances down the line. There are patterns, especially the API gateway, which brings a better orchestration with those numerous APIs. Orchestrating the APIs with optimized endpoints, request collapsing, and much more helps in addressing granularity challenges.