The API economy has ushered in a new era of application integration, causing a sea change across enterprise IT and application providers alike. APIs are providing access to data securely across firewalls, enabling new business models and offering a platform that supports the development of new digital products.

One Size Does Not Fit All

As API-centric integration matures, however, it has become very clear that not all API consumers are created equal: data objects may need to be modified based on the device type; orchestration or composition may be needed depending on the sophistication of the client; security might need to be adapted to fit mobile, web, or IoT scenarios. The list goes on.

A great example of this diversity comes from Netflix, where their API development team learned quickly that a “one-size-fits-all” approach to API integration wasn’t going to work. The team found that different client applications (such as a desktop browser, a mobile application or a smart television) required different functionality as they accessed the Netflix API, thus forcing the API team to build an increasing number of features to address the demands. Once continuously updating this single interface became unmanageable, they introduced an API experience, or mediation, layer on top of their existing API platform that allowed each UI team and even partners to optimize the API experience for their specific app or device.

With each new innovation in connected devices, and each new user and application experience that accompanies these devices, organizations must consider an application architecture and integration strategy that embodies flexibility and agility. API mediation (in other words: API experience management) is becoming a more familiar concept as many organizations begin to evolve their first foray into the API economy.

What is API Experience Management?

API experience management is a solution for enriching or personalizing interactions between distributed application and service components. The key to the API experience model is placing a new mediation or abstraction layer between API consumers (apps, services, and “things”) and API providers (services and applications). This layer wraps the backend API (the inner API) and exposes a personalized and managed API (the outer API) to each defined constituency of consumers, simplifying the developer experience while also ensuring loose coupling.

The new outer API may also aim to offer more advanced features to your developers, providing a facade on top of the inner API to enhance its functionality or simply keep pace with changes across API technologies and best practices.

Three functional areas you might want to consider adding as part of your API experience management include:

1. Eventing: There is increasing demand for event-driven integration patterns amongst web APIs, yet support amongst public and private APIs is still very limited. There is strong preference for webhooks to handle this asynchronous eventing between application services, so offering this functionality can be a valuable addition for your developers. Webhooks is even gaining a place within API documentation languages such as OpenAPI Specification v3.0.
2. Bulk Data Operations: Bulk upload and download operations are useful for many data-centric services and applications — and where available developers are often keen to leverage this functionality. If your backend doesn’t support bulk operations today, your API experience layer can be used to enable this.
3. API Discovery: To help relieve some of the pain of integration, API providers are increasingly offering a capability known as metadata discovery, so that data models and resource structures can be accessed and understood programmatically. Linked data can also enhance the usability and experience of your APIs, and again within OAS v3.0 there are new basic linking capabilities being described — a definite nod toward Hypermedia.

The Need for Mediation

Perhaps the simplest form of mediation is transforming legacy SOAP interfaces into more developer friendly RESTful APIs, but in today’s complex world of integration this isn’t enough to solve the challenges front-end developers are experiencing.

Rather than thoughts of divorce or separation that the term mediation may conjure up, this evolution is actually about providing a more positive experience for each of your API consumers. We’ve learned that quite often a one-size-fits-all approach to API design and exposure doesn’t work, and different types of users, developers, and devices have different expectations and requirements when it comes to API consumption.

API Experience Management in Practice

There are a number of key reasons why your organization will derive value from an API experience layer in your integration architecture:

• Change in integration requirements: You built out APIs to serve a single use case, product or business line, but now you have lots of constituencies each with different use cases and integration requirements.

Example: I have created an API designed to allow B2B partners to resell my products and services via their channels. When a new product owner wants to build a mobile application, this API is likely not optimized for the mobile web.

• Response to consumer needs: Your existing API layer has been in product for several years, and needs to be enhanced with new functionality your developers are asking for.

Example: My API is a basic RESTful interface which customers today must poll the endpoint when checking for updated data. They would prefer a WebHooks implementations that alerts their app when new data is available.

• Data governance: You need to synchronize data across a variety of services — even if they are in different domains. With many departments within an organization making their own purchasing decisions for the products they use, central control and data governance can be lost.

Example: If the sales organization selects Salesforce as their CRM platform and the support organization is using Jira, are these two organizations and products sharing data effectively? Don’t think about master data management, but rather a lightweight way to share and synchronize common data fields in each environment.

• Scalability over time: You are integrating to a particular service now, but in the future need to swap this for a new product or connect to multiple products.

Example: If I’m storing files in Box, and using Box’s raw API to do that, and then I add in SharePoint or Google Drive down the road, or swap them out, I have broken everything else, unless I mediate those APIs.

• Hide complexity: You have objects or resources that exist in multiple underlying applications, databases or other sources and want to provide consistent access to these as API resources to shield the consumer of the resource from complexity.

Example: Accessing a data object representing an “order” spans a number of systems — pulling data from stock management and eCommerce platforms. Developers should be abstracted from this complexity, only integrating with a single API that orchestrates the integration flows in the background to construct the data object.

• 3rd party app integration expectations: You are bringing a digital business application to market, and customers of this application will expect integration to the SaaS apps they use within their organization.

Example: You have built a new digital payments application and customers of this product need to be able to integrate this with their accounting applications (like Quickbooks).

Final Thoughts

Quite often across each of the use cases or scenarios described above, when starting with a small number of integration points (one or two), there is no need to worry about API experience management, since each API consumer can navigate any limitations. But keep in mind that once you start integrating more and more services, products, or serve different types of API consumers and an increasing number of developers, you’ll find that one-size-fits-all APIs become a barrier, rather than an enabler.