Three Principles of API First Design

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

Lars Trieloff
Jun 2, 2017 · 4 min read

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.

Follow the Adobe Tech Blog for more developer stories and resources, and check out Adobe Developers on Twitter for the latest news and developer products.

Adobe Tech Blog

News, updates, and thoughts related to Adobe, developers…

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store