When architecting software solutions, you will have a variety of different use cases to contend with. It’s important that these use cases are handled elegantly as part of the solution and as part of your API management strategy, and this is where API orchestration can come into play.
Rest API orchestration allows you to have a single REST API endpoint to do multiple operations by calling two or more REST API endpoints. From a pure fundamentals perspective, orchestration isn’t limited to API’s at all and technically a single service could provide orchestration to many other services with differing service technology all together, but for the sake of this article, we’ll focus on Rest API orchestration including microservices but fronted with an API management service.
If you are new to the concept of API management, it’s important to note that API management isn’t solely going to be used for orchestration, however, orchestration can be part of an effective API management strategy when designing your published API strategy and it provides a whole range of new possibilities. API management allows us to keep our core API’s internal and define which API’s are published and how they are published while encapsulating security logic policies, common authorization flows, caching, centralization, administration, instrumentation, versioning, subscriptions, and abstraction capabilities.
Let’s take a look, visually, at how API orchestration happens on a very fundamental level using API management.
In the example above, API orchestration has been used in order to facilitate a very primitive use case for a document management solution. “As a user, I need to publish a document” is about as fundamental of a use case that you can conceive. The capability to publish a document is fundamental and, I am, and you should be as well, a proponent of making your solutions’ API capabilities as simple as possible.
Sure, we could have demanded that any clients that want to use our API have to manually call multiple REST API endpoints in order to get the result they want to publish a document, but we are then introducing complexity and a higher chance of errors or mis-use of the API.
I wouldn’t recommend doing any kind of ETL or transformation inside the API management layer. It’s not what it’s for and it’s not a core capability of API management. Although you could conceivably hack something together, you really shouldn’t. Keep it simple, like in my example above. And although, technically, you could return a composite collection of the data from both outbound API calls back to the client, I’d recommend against it except under unusual circumstances. It is likely too much information and adds unnecessary overhead and complexity. I’d go for returning only the most relevant information back to the client from the most relevant concern, so in this case, the last API call made by API orchestration was to “Update Document Revision” which was used to publish the document. We simply return the response back from the second API call to the client and call it a day. Although, you shouldn’t be doing any serious transformation here, doing simple RegEx replacements or minor adjustments to the response to obfuscate the underlying API or provide your own metadata from API management is completely fine and a normal part of API management.
You may be thinking… “Shouldn’t we just re-write our core underlying APIs to expose a single API endpoint which handles ‘Publish Document’ internally instead of using API orchestration to string it together?”…. Yes, you could, but it’s not always feasible. There are pros and cons to every design decision you make, and although you may get a tiny performance benefit doing it that way, you may also be increasing the complexity on your back end. You may have a very rigid API from a vendor or previous development project that cannot easily be changed. The power of orchestration with API management is to be able to create a single API entry point to facilitate and simplify your API, but it’s certainly not the only pattern to achieve this feat.
There are some really good use cases where API orchestration makes sense., including:
- Reducing the logic required in client applications when performing commonly used tasks using the API
- Simplifying a vendor product or SaaS application’s API for consumption by your internal solutions for common use cases
- Simplify cross cutting concerns if you have Rest APIs that perform processing or logic and second set of REST APIs for persistence.
- Stringing together independent operations or microservices to provide a unified set of API capabilities to clients
There are also some very good things to think about when considering API orchestration:
- Although your calls don’t need to be, API orchestration tends to be synchronous, and that means your API management thread pool keeps a client thread alive for the duration of the entire orchestration
- Your ability to scale may be impacted and depending on your requirements and what scales to 10,000 requests an hour, as an example, may be perfectly suitable for your API orchestration, but, let’s say, you need to scale to millions of requests a second, you may potentially run into issues.
Scalability could be a concern given the considerations listed above. However, if you just remove the API orchestration you are left with the client making all the same calls but instead of orchestration from API management to your underlying API’s, your client is making these calls directly. This probably isn’t likely going to solve scalability concerns and you are removing the key benefit of orchestration from your solution of which is simplicity. Refactoring your underlying APIs in order to provide a single internal service to perform all of these functions may help, but then you are increasing complexity of your API which may or may not be ok – considering my example above, it’s perfectly conceivable to create a “Publish Document” microservice to handle, at least, this specific example. Other ways to mitigate these concerns could be to use the caching capabilities of API management depending on your specific use cases, or looking at infrastructure such as load balancing on an API gateway. API gateway’s provide a difference set of capabilities from API management and can be used to provide capabilities such as load balancing which can very well be an integral part of your overall solutions architecture.