Three Principles of API First Design

When developing cloud-native applications, “API First” is a core principle. Putting that principle into practice is harder.

In my conversations with developers who are looking to embrace cloud-native development and openness, one question frequently comes up: what exactly does “API First” mean? All too often, “API First” can come to mean “Yeah, APIs are important, but they’re not essential”.

There are three principles of API First Design:

1. Your API is the first user interface of your application
2. Your API comes first, then the implementation
3. Your API is described (and maybe even self-descriptive)

Let’s take a look what each of these principles mean.

API first thinking means that your API is the first interface of your applications. This means that the people developing against your API are your users, and your API needs to be designed with those users in mind.

Your API is how your product exposes its functionality, so if there is functionality in your product not covered by an API, it can’t be covered by a graphical user interface, command line interface, or voice interface either, effectively making the functionality invisible.

Finally, as your API is the first and most important way to access and interact with your product, the API needs to be managed and designed deliberately. Just as you spend time to design your graphical user interface, invest time to design your API: what it exposes, what it does, and how it grows.

Once you realize that your API is an interface that deserves attention of its own, you begin to realize that the API has — and should have — a life of its own.

Your implementation will change as your application evolves and you optimize, refactor and grow the functionality. Your API, however, should not change frequently, but instead grow slowly and deliberately.

Your implementation will change frequently, your API should not.

Here’s another way to think about this approach: If your API is the surface area of your product; the functionality is its volume. Doubling the functionality will only grow your API surface by 25%.

It’s important to think of API evolution in terms of growth and increasing flexibility. Graceful API evolution is additive in terms of functionality, and subtractive in terms of requirements. While change is inevitable, planning for a graceful API evolution is a good way to minimize changes that break things. For example: required input may become optional, but not the other way around.

Treating your API as independent from the implementation, even if that’s harder, allows you to decouple development of API and implementation. Your API becomes a contract and specification to the implementation, instead of just being a thin veneer on top of your implementation.

The third principle of API First Design is about descriptiveness. In order to be used, your API needs to be easily understood by people that have not been involved in its creation. That means documentation.

Usable API documentation is an essential prerequisite to making it consumable by humans. As robots and AI aren’t taking over programming anytime soon, this makes it essential.

When it comes to documentation for APIs, structured documentation beats unstructured documentation. Following a standard pattern for URLs, resource types, request methods, headers, request parameters, and response formats will make it easier to explore and understand functionality, and reduces surprises when your API grows.

Speaking of surprises: in your API design, try to minimize surprises and follow established standards and best practices wherever possible. When it’s impossible to do so, document the deviation so that your API consumers won’t waste hours chasing a bug introduced by an API that is working just a bit differently than expected.

There is one thing that makes even the best documented APIs stand out: APIs that are self-descriptive by using hypermedia constructs like links that allow the discovery of other API resources. This gives you a great way to close the loop from design, over implementation, to documentation.