A small riddle in the beginning. If you have one API, you don’t notice lack of it. If you have two APIs, you probably don’t notice the lack of it. But if you have 3 or more APIs or multiple teams working on your APIs, you will notice the lack of it. What is it? It’s the API Design Guide.

According to State of API 2019 “Standardization is the #1 API technology challenge facing API teams”. What does standardization and API Design Guide have to do with each other? How does DX and standardization relate to each other? We’ll come to those questions in a while.

In the same report it was stated that Developer eXperience is the second most important aspect to measure API success. The results were based on a survey which was open for 2 months and gathered staggering 3372 responses.

Not a big surprise (but still raises a smile on my face) is that companies are waking up on the importance of API documentation. According to the report 57% of respondents that said API documentation was a top priority also said that they would rate their existing documentation as good or very good. In contrast, only 9% of respondents that do not currently have an API documentation process ranked their documentation as above average. More than half of API consumers cite ‘accurate and detailed documentation’ as one of the most important factors they consider when evaluating an API. The only factors viewed as more important for consumers were performance and usability.

API Design Guide standardizes otherwise volatile development

API Design guide defines rules for API design. It often defines versioning policy, naming style, date formats, endpoint structures and more. It’s a bible which gives more than 10 commandments for API implementation. Since every aspect of the implementation does not have to invented again and again, it saves time. Also if all follow the same rules, then the API family will feel the same and consistent. That is a huge value for the API consumers. If your guide uses industry standards as well, then the learning curve is lower for new API customers. You might have multiple distributed teams developing your APIs. They might even be subcontractors. If you have proper design guide, all the teams get read and adopt the same practices. Again that might save a lot of time and refactoring and minimise the endless debates for example about date and time formatting. Besides consistent code is easier to maintain. In short, API Desing Guide standardizes the API behaviour, partially the development and for sure the Developer eXperience.

The above is the traditional list of benefits of API Design Guide. That was easy to write from top of my head. Another use case came to my mind as well. If you are acting as subcontractor for some organisation and they are developing APIs, but they are not so familiar with API development. They might not have API Design Guide. In that situation your company might have your own version of it and offer that to be used. In best case, the customer wants to adopt your API Design Guide as their own version. But for sure having one will make your work easier than starting the discussions and reasoning for certain aspects of the API with the unfamiliar customer. Even if the customer wants only 1 API, having ready-made design guide simplifies and shortens the timespan of the development.

Some times desing guide is expanded

At Platform of Trust we started with API Design Guide. It was seen necessary because we had 6+ APIs and that count was probably rising. On top of that we have several teams working on APIs. After a while we discovered that the concept should be expanded to platform level. We renamed the API Desion Guide to Platform Design Guide. In our case we add also UI/UX elements, standard data ontology and API Documentation related guides and practices to the guide. This is work was started just recently. Crafting design guide while building the platform is a challenge. Thus our design guide is pretty rough and battling for resources required elsewhere. Nevertheless, it’s building and the value of it is evident already for part of the teams. Not all are convinced yet, but that’s just matter of time.

By the way, if you want to look at API Design Guide examples, go to http://apistylebook.com/design/guidelines/


Some more to read from 100 Days DX