The API space is ever-evolving. As the needs of end-users grow in both complexity and frequency, new software development strategies continue to emerge. When working with APIs, it’s not uncommon to see a network of systems handling a single purpose. In fact, during the modern age of microservice architectures, this has become the design paradigm de jure, with each API operating a small fraction of the much larger machine.

With that in mind, how do we ensure that those systems work effectively and smartly in concert? Today, we’re going to look at a solution to that problem in the form of orchestration.

What is API Orchestration?

At its core, API orchestration is the act of integrating two or more applications into a single, unified offering. Typically, this is used to merge API calls into a single frontend, automate processes, or merge multiple internal APIs from a user experience perspective.

Let’s construct a case where orchestration might make sense. Imagine a city of the future has decided to build a bike rental system. This system allows for users to rent bikes for a modest fee – if the user pre-registers and provides evidence that they are city locals, however, this rental is subsidized and made free. Such a system would be quite complex. From a user perspective, it would have to support several distinct APIs and would have to be able to verify identification status through something like scanning the magnetic band on a driver’s license.

Digging further, we would need some specific APIs to support a sort of maintenance tracking system to ensure bikes that are damaged are repaired. Additionally, there’d need to be a storage API, a payment API, and several others. More to the point, this entire system would need to be presented in a clean interface without requiring the user to jump through too many hoops.

If there was no orchestration happening behind the scenes, each step of this would be needlessly complex, and the user experience would be fragmented across multiple machines and screens. With orchestration, however, the user can use a single interface, with everything else occurring seamlessly, hidden behind a single entry API.

Sounds good. How does that work, exactly?

How Does it Work?

While there are many different solutions that can fall under the umbrella of orchestration, we’re going to use our example to build out what an effective orchestration implementation might look like. In our example, we have several very specific APIs that must be coordinated in concert to provide a single service. The most effective method for synchronizing them is to use a single orchestration API to tie everything together.

Before we begin, we should note that the key to this sort of implementation is the heavy use of federation. We’ve discussed federation at length before, but simply put, federation is a method of trusted interaction. A collection of services, usually under the control of a single entity, can develop a federated system in which each element of the systems trusts the authentication and authorization schemes from their respective services throughout the greater system. In our case, we have some segmented authentication and authorization schemes that we can leverage to provide a unified experience, as long as the orchestration API handles the sending and receiving of each element of those individual schemes.

First, let’s list out the systems that we need to orchestrate:

• The front-end API: This is the API that the user is interfacing with, and will serve as both the primary entry point to the orchestrated service and the collater of internal API responses.
• The ID checking API:  This API will need to accept credentials from the front-end API and match the data against publicly available resources. In our case, to protect privacy, this system will need to be opt-in, so the API will interface with database storage systems and a website application which allows users to register their status.
• The bike management API: This API needs to talk to other kiosks as well as connect to a database which stores the status of each registered bike. This allows for the management of inventory but also ties into a subset of functions which notes bikes that need repair through self-provided user reports and routine mechanic visits.
• The storage API: This API would be needed to drive the mechanical storage system which keeps the bikes enclosed and safe

The elements at play in our API orchestration scenario

So what would the orchestration API look like? First, the API would need to use federated identities from the individual system’s components. It would do this by using a generated authentication token trusted throughout the system. At each stage of this orchestration API’s interactions, this token will be used to guarantee that the information, requests, and validations are coming from a trusted system, and as such, can be utilized on each API.

Now that we have that out of the way, we can begin to build the flow which will leverage the orchestration API. When the user inputs their credentials, these credentials would need to be encrypted and sent as a secure package to the ID checking API, leveraging the orchestration API as an intermediary.

Once this API verifies the information, two different responses need to be generated. First, the positive response to the front-end so that the user knows their ID has been accepted, and then a token for the bike itself, which needs to be sent to the storage API. After the user gets their positive response, and after the storage API receives a request, the bike itself can start being moved to the user. At this time, a secondary set of responses needs to be sent by the storage API – one telling the user the bike is on its way, and one notifying the bike management API that a bike is being “checked out.”

The bike management API can then use internal camera footage (triggered by the API and stored using remote resources) to record the status of the vended bike before its handed to the user, storing this data for future use by sending the data through the intermediary orchestration API into a remote management service.

Finally, the bike can be vended by leveraging the front-facing API to open the doors once a bike is sensed.

Of note here is that at every stage of this process, we have had a fundamental transformation of the request from one form to another. Each request has been made using the APIs specific request format pertinent to that request. Not every API will expect that format, however. For example, the bike storage API is not going to expect a request in the format of the front-end API. As such, the requests made herein are essentially translated, transformed into intelligible content, so that the request stays the same throughout each different environment.

Without all of this orchestration, what is a 3 screen process could become 10 or more prompts over multiple interfaces. That is the power and value proposition of an orchestration API.

Extending Functionality

With an orchestration API managing these interactions, we can take the system a little further. Perhaps we have a kiosk which does not have any bikes. Do we want this process to repeat for every request knowing full well that the kiosk will be unable to fulfill any orders? Using caching, we can store the status from the storage API on the user side, skipping all request steps and simply notifying the user that the kiosk is empty.

What about a use case where we want to allow multiple people to check out bikes using the same ID? For instance, if a user registers their ID and notes a family of three, perhaps we want to allow that user to rent up to three bikes in a single requesting session.

In such a case, we can cache the ID information to resend to the verification API, which needs to be done since each bike is handled as a distinct unit by the storage API. By storing the credentials for re-sending per each specific order, we can prevent the user from having to re-scan their ID, re-provide credentials, etc.

Orchestration for Other Scenarios

Moving away from our example, there may be situations in which we need additional info to transform our requests, and here, orchestration adds value once again. For instance, if we were instead using API orchestration to allow students to register for classes, we might want to have priority seating based on registration date. In such a situation, we could have the requesting API sit by and hold the cached request as submitted by the student while the status of the student registration date is fetched.

When the date comes back in, that API may want to use the transformation system to change the original request by adding information to the request field, changing the request priority seamlessly. The student would be notified of their priority, and their request would be properly filed away in the order in which it will be filled. In such a way, we can use both caching and transformation through the orchestration system to automate much of the student registration and seating allocation process.

Conclusion

Orchestration is a simple concept, but it’s often seen as an extra step that only adds complexity. In reality, it is a complexity that overall make systems simpler in certain use cases. In our use case, we dropped from a user flow over ten or more screens to a single, unified experience happening over two prompts: scan your ID, request your number of bikes. That sort of power is incredible, and the underlying system can lead to all sorts of unique innovations.

What do you think about orchestration? Is it more complex than we’re letting on, or perhaps more simple than we’re making it? Let us know in the comments below!