As a great fan of API-led integration technology, I want to highlight some ideas and approaches that need to be considered before starting with the design for a API network. Actually, I am working with MuleSoft and some of the technical terms refer to this integration platform. Please bear with me but I believe it is the best solution, but I am convinced that the basic idea of this article applies to other API-led integration solutions as well.
The one or the other may remember discussions from the “Platform Architect” course. We discussed in and out the benefits and pitfalls of the fine grained and coarse-grained approach. After some months working with MuleSoft my understanding of the differences and reasons for the one or the other is more transparent as it was before.
Do you believe that API design is important? I hope you do. If not, you may run into serious problems in later stages of your integration project. The simple difference between “fine-grained” and “coarse-grained” is – please allow me a first and simple approach to it – the number of APIs based on the same number of system integrations and non-functional requirements.
In other articles, the concept was introduced as the “right-grained” APIs. This implies, that there is “one” correct approach. I doubt, that this is the case. I also heard about “right-grained”. Even within one network, it could be beneficial to balance between these two and slightly change the approach depending on the requirements. Does it make sense to mix both approaches within one network? I think not. There are many reasons, which will be outlined in the next chapters. Besides, I have not seen a working network where the team used “vanilla” fine-grained and coarse-grained together and was successful in the end.
Let’s look at some formal aspects of the two approaches:
Maintainance
At first glance, coarse-grained APIs seem easier to maintain because there are not so many APIs. If you already have a relevant number of APIs and try to fight your way through the jungle, you may know what I am talking about.
Error handling
Are you using APIkit implementations? Then you may use error-handling on the level of the Router Flow. Let’s talk about a practical example. You have either only ONE SAP System API or you have created 10-30 based on the required entities or business processes. More APIs give you more flexibility in defining alerts or error flows. However, they may also lead to unexpected complexity through redundancy.
Communication
If you use the network for communication and reporting to other lines of business, then the fine-grained network brings more benefits.
The description of an API is clearer and leads towards the real business process, if there are more APIs instead of just one “Order Process API”.
Elegant development
I am not sure, whether elegant development is a KPI for your team – probably not. However, from an API developer perspective, a fine-grained approach makes the most sense, because it allows the developer to structure the flows and therefore the implementation of the API more effective and transparent. The flip-side of the coin is the possible duplication of code/components. In order to avoid this, some experience is required, not only from the developer but also from the CoE (if there is one) or the project management.
Licensing
You always need more CloudHub workers if you have more APIs, even when they are “smaller” from a functional perspective. This is a potential downside in terms license-costs. License costs are measured in vCores as you probably know. Each CloudHub worker need at least 0,1 vCore to be created.
Readability
I think it is fair to say, that smaller APIs can be easier understood and read. The more assets you have, the better you control the network from a functional perspective. Does that contradict my previous statements, that that as more API’s you have that this is harder to maintain? Not necessarily, it is just the flip side of the coin. The decision of the Mule architect is simply what counts more in the specific case. Either you want to have atomic functions which are easy to understand, or you like less API’s which are better to maintain from a technical perspective.
You have to make sure, that everybody understands the meaning and interactions between the APIs.
Performance
Performance could be the most important non-functional requirement for a project that implements an API network. The number of APIs influences the performance in several ways. The most obvious reason is latency. The more APIs, the more transformations and probably more HTTP requests in and out which creates a higher latency. If this is critical for you, this leads to fine-tuning API parameters and requires caching or intelligent ways to parallelize the integration flow.
Believe me or not, in the end, the reliability and acceptance of your integration network will depend more on other factors. However, the way towards this holy grail can be dramatically influenced by the decision how you design your API network.
API FOREVER!
