RESTful Java Web Services - Second Edition

Fine-grained and coarse-grained resource APIs

While building a RESTful web API, you should try avoiding the chattiness of APIs. On the other hand, APIs should not be overly coarse-grained as well. Highly coarse-grained APIs become too complex to use because the response representation may contain a lot of information, all of which may not be used by a majority of your API clients.

Let's take an example to understand the difference between fine-grained and coarse-grained approaches for building APIs. Suppose that you are building a very fine-grained API to read the employee details as follows:

• API to read employee name: GET /employees/10/name
• API to read employee address1: GET /employees/10/address1
• API to read employee address2: GET /employees/10/address2 ...