A Few Simple Tips for Implementing Kick-Ass APIs
In this article, I will be sharing tips learned from experience about implementing APIs, kick-ass APIs!
Why implement APIs in the first place?
An API is a great way to define a boundary that defines the interaction between API users and API providers. This achieves the following outcomes:
- API users know only about what an API does and how to integrate with it successfully, and do not require knowledge of its underlying implementation.
- API providers document what an API does and how to use it, and retain the freedom of changing the underlying implementation of the API as they see fit.
What makes an API a kick-ass API?
A kick-ass API is defined by its ease of use. It should be easy for API users to understand what an API operation does, its inputs and its outcome. It should be easy to integrate, easy to test, and safe to operate.
Also, a kick-ass API never breaks, continuously evolves, delivers value, scales and performs accordingly.
What kind of APIs make for kick-ass APIs?
Let’s start with the ones that do not make for kick-ass APIs: Web Services, SOAP, XML/Atom-based APIs. Although these types of APIs have proven to work and deliver great value, tremendous value even, they have also proven to be tremendously costly to integrate, maintain, evolve, operate, change, retire, decommission, exterminate… It is a minefield yielding to over-engineered, overcomplicated and coupled systems.
What is left then?
Well, we might have read about REST, HATEOAS, Richardson Maturity Model… All fine and good… elegant, smart, clever… sometimes genius. But is this the perspective of API users or API providers? I have to admit that there is an engineering delight into achieving the highest level of maturity in the Richardson Maturity Model which yields to a glorified REST API! But honestly who cares? Do API users see the same great glory in this model or is it just an over-engineered API yet again?
So what then?
Well, a good principle here is to Keep Things Simple Stupid. HTTP is a great specification of a protocol that defines the semantic that API users would expect and API providers should support.
Is that it then? HTTP really? What about the content type to transport data?
JSON is a good one, JavaScript Object Notation, I love it. It is concise enough, readable, easy to learn and easy to shape. It has everything an API needs to handle data, no more, no less. Also, it comes with a schema, which is a handy way to specify and validate the shape of the things that an API supports.
Are we saying that HTTP and JSON are the keys to implementing kick-ass APIs? Isn’t this the same as REST?
Well, not quite, it is a simplification over REST, a style that exposes HTTP endpoints as operations able to process data in JSON, without the complexity of managing resources exposed in a REST API via their URIs.
But there is more to it, and this lands with solving a complex problem via a simple interface. Remember:
Perfection is achieved, not when there is nothing more to add, but when there is nothing left to take away (Antoine de Saint-Exupéry)
Great APIs focus on users’ needs and offer intelligent ways to fulfil these needs by adopting a language understood by their users.
As APIs are a way to communicate information between two parties, great APIs adopt a language that resonates with the one spoken by their users. Defining such language should drive the naming of endpoints and the naming of the things processed by the API. It is key to elevate an API to the level where users can reason about this API and understand how they will use it to support their functional needs without having to translate their domain into technical terms.
Domain Driven Design and the exercise of defining the ubiquitous language spoken by both API users and API providers will greatly contribute to the ease of use of an API, prior to anything being implemented. As an API is designed, it is the responsibility of API providers to ensure that the language spoken by their APIs is understood by their targeted API users and resonates with their users’ needs. It is then critical to capture this information by engaging early with API users, showing these users drafts of the API, and functional scenarios supported by the API. Demos, workshops, inviting customers, but also looking at how other companies do it, all contribute to an ongoing feedback loop that will help API providers design kick-ass APIs.
There are usually two classes of problems that APIs solve:
- Ingesting data
- Accessing data
On the data ingestion side, let’s try to make it as easy as possible for API users to ingest the data needed by API providers.
What can we do to make data ingestion easy?
Find out about the origin of the data that API users are intended to ingest, shape it using a language that is easy to match with API users backend systems, and make the effort required for successfully ingesting data as little as possible in order to start operating with the API successfully. As an example, design your API to require only the minimum amount of information that is absolutely critical to the underlying system and leave the rest optional. Let API users decide what additional data can be added, for which purposes, so that API users gradually increase the value achieved by their API integration.
Ideally, as long as the data being ingested is compliant with the schema specified in API definition, API producers should just accept it, and then let internal processes enrich this data to deliver the targeted value.
On the data access side, API users need to access the information they need using the information they know. So, API providers should focus on exposing and enriching access patterns that will best support their users. Defining how information is accessed is critical to the ease of integrating with APIs. The good news is that such access patterns are already known as they can be derived from the language spoken by API users when they talk about their functional needs. And when API providers get this right, it makes for a kick-ass APIs!
What about making APIs safe to use and safe to operate?
It is the responsibility of API providers to guarantee that APIs can be used safely by their API users. This can take many different shapes and forms driven by what APIs do and the nature of the data being processed.
API providers should know about who uses their APIs using adequate identification mechanism of their API users. They should also ensure that API users are authorised accordingly when ingesting and accessing data as to guarantee the integrity of the data being processed by their APIs. Transport of the data should be encrypted obviously. As for storage, it has to be done in accordance with the sensitivity of this data (encode, encrypt, redact).
At the end of the day, API users decide if an API deserves the title of kick-ass API, only then can API providers claim that they have done it!
More content at plainenglish.io
