Fine-Grained vs. Coarse-Grained APIs in MuleSoft

API design is a fascinating topic. One important aspect of API design is determining the right 'size' of an API in terms of its features and functionality. All architects must have grappled with this issue at some point or the other. In this article, I will try and give some insights into the various parameters that we need to think through before arriving at the 'right' grained API:

• Maintainability: The first aspect that comes to mind is the maintainability of APIs. Coarse-grained APIs are difficult to maintain. As the API consumer needs grow, it will be difficult to add more implementation variations or parameters.

• Management: In MuleSoft, we can use API Manager to manage each API separately. This means that we can enforce security policies like IP Whitelist, IP Blacklist, Rate Limiting - SLA Based, JSON Threat Protection, etc. to each API based on its need. Since each security policy adds a small latency, this becomes an important consideration. 

• Error Handling: You can apply a cleaner error handling in different APIs. This can also lead to defining MuleSoft alerts for different APIs

• Deployability: Fine-grained APIs are easy to deploy. If versioning is properly followed, we can deploy smaller APIs quickly and roll out functionalities to the market in a more agile manner. This typically results in shorter innovation cycles because changes and new features can be deployed into production more swiftly

• Scalability: Cloudhub workers are allocated to each API implementation independently, and can therefore be tuned (scaled) to each API implementation’s specific needs

• Resources: Each API implementation, however small it might be, consumes a minimum set of resources (CloudHub workers) and more API implementations — even if they are smaller — typically
  means higher resource usage overall

• Complexity: Smaller APIs and API implementations are simpler and therefore more easily understood and maintained. Compared to larger and hence fewer APIs and API implementations they also result in more API-related assets visible in the application network and more and more complex interactions (API invocations). However, a large system with many fine-grained APIs would be very complex owing to the interactions between these APIs

• Latency: Each additional API invocation adds at least a small amount of latency, and smaller APIs, therefore, cause higher overall latency, which often must be mitigated through caching, etc. Consider this parameter carefully for experience APIs. A mobile order API would be much more sensitive to latency than a web-based order API.

• Failure modes: Each additional API invocation is an additional remote interaction between
  application components, the potential failure of which must be addressed. On the other hand, coarse-grained APIs might become a single point of failure.

• Organization Structure: In any big organization, different lines of businesses must interact with each other if they have different bounded contexts. With fine-grained APIs, each API can be implemented independently of all other API implementations, assuming that the application interfaces between API implementations — in the form of API specifications — have been agreed. This means that team organization and parallelization of implementation effort are more flexible with fine-grained APIs and API implementations.

It is important to remember that the overall functionality remains the same with both the approaches, but you end up with significantly more endpoints with a fine-grained API approach. As a developer, you can be assured that your code will be more structured as each API corresponds to a different operation. In most scenarios, you would need both kinds of APIs.