API-First Development Strategy

The API-First approach doesn’t only change the type of consumers but also the product lifecycle, requirements gathering, and the chosen technologies.

Product Lifecycle

Traditionally, an API was developed as a supportive element for consumers, not a standalone product. This made the planning and development easier, as the API lifecycle was tightly coupled to these consumers.

The API-First approach changes this quite a bit. It needs to be a standalone, long-living, and maintainable product that must fulfill existing and future consumer requirements. The API must be independent of its consumer's lifecycle and their needs. In most cases, the API will live long after consumers come and go.

Requirements Gathering

You may ask yourself: how do you gather requirements of API consumers which will come up in the future? There are two ways to tackle the problem.

Exposing as Required

When you build traditional APIs, you'd ask yourself what data is required for our consumers to fulfill their requirements. In simple language: which part of the data I have to expose so that all our consumers are happy.

This will lead to frequently updating the API as new requirements or consumers come up down the road. Or you'll overengineer an API to make everything possible you can imagine, which is hard to build and even harder to maintain.

Protecting Data

The API-First approach works the other way around. You want to expose as much as possible to make all kinds of products possible based on your API. Instead of collecting requirements and asking yourself what your consumers could in future need, you think about the data and which part shouldn't be exposed.

Choice of Technologies

REST is probably the most famous type of API. It's powerful, but it also has its limits. It was built back in the days when requirements were very different than they're now. There are many different technologies out there, but for the sake of the post size, I'll only talk about GraphQL.

GraphQL

With GraphQL, you define the data schema you want to expose with all its nested relations. To make these accessible, you expose queries, and to edit the data, you expose mutations. If you want to build a live-data application, you can expose subscriptions. That's the concept of GraphQL.

You can now provide the same API for a simple read-only application, a data editing backend, or a live-data dashboard with all its features. Because you expose the whole data structure, each consumer can ask for the data required. There is no over-fetching or multiple requests at the same time.

With GraphQL, you get not only a powerful API, but also a big community with a lot of tools and open source projects. For example, you'll get auto-generated documentation where you can try out the API live queries. Or you're able to generate code for a different type of clients/language based on the schema you expose. The list goes on and on.

As good as this sounds, GraphQL is not the silver bullet we all wish we would have. There are some challenges you'll face with it. It's up to you to decide if the benefits make it worth dealing with the challenges.