Good API design is a recurring topic for teams trying to perfect their API strategy. That’s because a well-designed API leads to a better experience, faster documentation, and better adoption of your API. But what exactly goes into a good API design? In this post, we’ll detail some best practices for successful API design.
API design is a job in itself. A sloppy design, based on the field rather than based on analysis, with APIs invented on the fly and without hindsight, usually produces a poor developer experience, with the risk that the API will be little or poorly used, which would be against its purpose.
The reason is simple: OpenAPI allows the generation of documentation in an automated way, so the documentation will be the reflection of the design choices. A bad design will therefore be difficult to interpret, or even unreadable.
How information is exposed via the API matters as much as the ability to expose it securely and seamlessly. Design thus takes the lead in the API building process. We talk about Design-First. It’s nothing more or less than laying out the plans for the API before you start producing the first line of code.
Transversality and Design-Thinking
For APIs, the challenge is transversality: by introducing design upstream, we can meet with the stakeholders of this API and build it while respecting the majority of the requirements expressed. Without this work, we would end up with a first version that follows the recommendations of a single category of users, and future developments would probably quickly force us to disregard this first contract, sometimes to a considerable extent.
This transversality is generally organized in Design-Thinking sessions applied to APIs, which are particularly well suited to the fact that an API provides a service and is described as a product. Astrakhan offers in its training catalog “Digital Leadership” a Design-Thinking module applied to APIs, as well as Design-Thinking applied to Data.
The main contribution of Design-Thinking is to limit the effects of the most obvious bias: an API built to reflect the systems it connects to, rather than the views of those who will use it. Customer journeys in banking or Online+Offline (O+O) omnichannel in retail will benefit from this approach.
The design approach is then completely architectural since it will consist of progressively building the target API by bringing together all the requests. The initial collaboration thus temporarily gives way to the know-how of the architect who will bring together the requests in a coherent way.
We can wonder if this approach is linked to the use of REST and if GraphQL will not make this whole approach obsolete. This does not seem to be the case. GraphQL is indeed easier to access and offers a better developer experience at first glance. However, in our opinion, the design work must remain free of architectural choices and be done upstream, especially since the scalability issues surrounding GraphQL make it difficult to consider it as a solution that can cover all use cases.
Conventions and rules
Next, it is generally useful and necessary to rely on the conventions that have been implemented to facilitate the way your API is approached by its future users. If the conventions change from one API to another, it will be badly perceived to have to enter several design techniques, which are sometimes contradictory.
The use of names for resources, the consistent use of HTTP verbs, the reinterpretation of HTTP statuses in a unique way, the distribution of information in a unique way between header, parameters, variables, body, etc. are all practices to be favored so that all your APIs have the same signature.
Beyond that, it will also be necessary to standardize the practices of paging, filters, hypermedia links… or to specify the recommended and available options.
Links with enterprise architecture
Generally speaking, this means linking the design of APIs to information models, and therefore implicitly linking them to prior modeling work, which is not in itself revolutionary, since this was already the case at the time of service architectures, which are so criticized today.
In general, it is the link with the enterprise architecture work and the repositories where it is implemented that should be used. This is a good way to ensure the compatibility and reusability of the work. Astrakhan is currently working on implementing an API management vertical on the solution of its partner “Ardoq”.
This can be seen as a sign of the times and of a certain standardization, where new technologies have taken over old ones, while ultimately perpetuating the elements of method that they claimed to be able to avoid. This is not too important and is rather good news, since it indicates a tendency towards modeling, standardization, and the definition of rules, for a digital economy that used to pride itself on not respecting any rules. But it doesn’t matter, because it has taken over and happily modernized everything in its path.
