API’s & Interoperability

Interoperability is a unique characteristic of systems to be able to efficiently communicate and work together. Good examples of effective interoperability are the various standards for images & videos. JPG’s, PNG’s & MP4’s are all interoperable across all digital devices as the standard allows them to maintain compatibility to ensure all devices are able to send, store & retrieve these formats consistently. This concept of effective communication is at the heart of interoperability & for traditional organisations in certain industries this manifests into complex organisation structures which become more challenging over time to unbundle & maintain a high-level of innovation.

API’s are an effective method to start exposing core business functions via standardised interfaces such as REST. These API’s themselves evolve to become products in of themselves to external partners & developers which in turn enable innovation through becoming the key infrastructure for developers to build digital products. With the technology landscape evolving with AI, we will see an increase in demand on organisations to build API products.

Amazon provides a compelling example of this transformation. The famous Bezos Mandate transformed a traditional e-commerce organisation into one of the world’s largest cloud providers by exposing core business functionalities as services throughout the organisation—now known as AWS. This raises important questions about our current approach to APIs within our organisations: Are we building our API’s to be more than just ways to expose data? Are we designing and developing APIs in ways that truly enable innovation as Amazon did?

Put the User First

As developers, we often approach API development from a data-first perspective which can be an effective way of exposing system data over the network through protocols like HTTP. However, when other users utilise our API’s to build digital products we should attempt to shift our approach similar to how we would for user-facing web products. As Stripe emphasized in their 2019 conference around API Design Principles, our primary aim should be to keep the user’s requirements first, treat API’s as first-class citizens and look to continuously incorporate their feedback into the design.

The process for this can differ per organisation but this could entail working with UX teams or customer journey specialists to understand how the customer or user wants to interact with our API’s. These interaction requirements will also differ depending on the industry context we’re working in, for example there will usually be more focus on faster lower-latency API’s within an e-commerce ecosystem, however, the required quality attributes for the system should drive the decisions we make towards the API design & experience.

Lets take another example of Amazon which was adopted by Stripe through the process of “working backwards”. This process starts from a press-release which entails a description of what the product does, why it exists & what problems it solves for the business. This information provides valuable feedback from the potential users of the system & should start to answer some key questions the API producers might have to identify the required quality attributes of their API such as;

1. Does the user understand the intent of the API and did it solve their problem?
2. Does the user understand the domain boundaries of this API and what its responsible for?
3. How efficient was the developer experience for onboarding the user?
4. How easy was it for the user to integrate with the API & can we identify any technical improvements we could make to improve their experience for e.g. providing this data via events or through other protocols instead?

The key point here is to model our API products around the user’s requirements & expectations as these metrics will be the drivers of the adoption & evolution for our API’s.

Visualise the Business Intent

An initial factor to consider when approaching our API design is to check whether we’re visualising the intent of the core business function in our API resource structure or whether its only really just a CRUD (Create, Read, Update, Delete) operation.

As mentioned in the previous section when building user-first API’s our primary concern should be the users perspective and whether they can translate the business function of the API just from its design.

Lets look at a simple example we might see for an e-commerce application where a user can add an item to their shopping basket.

One way we could look to expose this function is via a REST API with a PATCH HTTP method to select the item;

PATCH /item/select

Request:

{
  "item": {
    "id": "123",
    ...details
  },
  "basket": {
    "id": "",
    ...details
  }
  ...
}

Lets compare the “users” requirement from the API which would translate to something like;

I want to add this item to my basket

Analysing the API resource structure will translate to something quite different;

I perform an update to select this item

We can see a difference in translation of the intent of the operation we’re trying to perform between the user & what our API is actually doing. This places the responsibility on the consumers to piece together their perspective of the business intent from the various CRUD API operations which impacts the interoperability across our organisation & with partners. All consumers now have a different understanding of the core business function which majorly slows down the delivery capability of building effective products within the organisation due to additional requirements for alignment.

The diagram below shows where the translation of understanding the business intent is with the above scenario and how each consumer could easily have different perspectives of the API’s purpose;

A key enabler to faster time to market is a shared understanding of clear business intent from our API products, this shifts the translation of business intent away from our consumers to the owners of the API product.

There are many levels on how we can visualise the business intent and can be as simple as starting to treat our API’s as first-class citizens. However technically for developers & architects we can make some practical changes straight away to how we approach the API resource & payload structures.

Going back to our e-commerce scenario, we can better visualise the business intent of our API resource with a few basic changes;

1. Structure the operations around your domain & sub-domains
2. Ensure the structure aligns to your user’s requirement

Following these steps we can model the operation around the core entity which in our example would now be the basket;

POST /basket/{basketId}/items/{itemId}/select

This translates much more closer to our user’s expectations;

Select this item into this basket

There are many levels on how we can improve interoperability across the enterprise but we can start this process through better API design practices which allows the organisation to map out the core business functions across the enterprise landscape & identify ways to optimise duplicated functions.
In our next blog post we’ll start to delve deeper into API design practices such as leveraging Domain Driven Design principles & the aggregate pattern to identify better logical boundaries for our API’s.

Conclusion

Through API’s our aim should be to have a view of the building blocks of core business functionalities which are aligned to the business domains to accelerate the capability within the organisation to build digitial products. There has never been a more crucial time for creating these effective API products with the rise of AI solutions & new protocols like MCP which are placing more emphasis on strategic API’s that are clear in their business intent to enable the next generation of digital products.

Links & Resources

https://nordicapis.com/the-bezos-api-mandate-amazons-manifesto-for-externalization/
https://itrevolution.com/product/unbundling-the-enterprise/