Many of us have heard about API Design Guides. Probably less of us have used those though. Even less have written such a document. I would guess that most of the people messign with APIs see the API Design Guide as something that defines error handling, naming patterns and all sort of detail-alike guides for designing and implementing APIs. That is one point of view.

One of the purposes of API Design Guides is to ensure consistency among multiple APIs. This in turn has at least four values:

These values alone should broaden your viewpoint beyond the traditional “error handling and naming patterns” perception. API Design Guide is also part of your API strategy. Read further and you’ll learn why.

What is commonly found in API Design Guides?

Murphy et all (“Preliminary Analysis of REST API Style Guidelines, 2017”) analysed 39 API Design guides and found pretty obvious topics in the top 10 items discussed in API Design Guides.

Analysis of the guide documents revealed patterns in popularity of topics and even sub topics inside of the categories. Of all the 27 categories identified, five of them (Versioning, Naming, Response Structure/Format, Standard Methods, and Status Code) are mentioned by at least 27 of the 32 guideline documents.

Status codes

Thirty of the 32 guideline sets provide rules for status codes – indicators of the success/failure of an HTTP request – and many of the codes overlap. A few talk about status codes in a general sense, suggesting to use commonly understood codes but to be as specific as possible.

Structure and format of the response

REST API guideline sets include several rules about the structure and format of the response that API users receive after a method is completed. There is a general consensus that JSON should be used as the default format. To pretty print or keep the response minified is something that depends of the guide. Other rules under this category include the format to use for date and time (where some recommendations specified ISO-8601 format and others specified RFC-3339 format), how to present nested objects, and the format for linked elements, as well as rules about what object types to use within a response.

Standard methods

HTTP defines a variety of standard verbs – which indicate an action to be performed on a resource or identifier – and most guideline sets recommend using at least GET,POST, PUT, and DELETE as their methods. Rarely guides go into depth, explaining which verbs should be idempotent, cacheable, or have side effects.

Standard methods are a popular topic to cover in guidelines sets, likely because of their fundamental role in REST APIs. Analysis across guideline sets reveals a high level of consistency and agreement as well, which is not often seen in other topics.

Backwards compatibility

Despite the fact that backwards compatibility is a key aspect of API design, only 12 of 32 guideline sets provide rules on backwards compatibility. What is and what is not backwards compatible change is something that varies among the guides. Rules for determining backwards compatibility seem to be based off of what would intuitively be most likely to break code. Though there is disagreement about whether adding a field is considered backwards compatible, other rules do not seem to differ among guideline sets.

API Design Guides are often detailed documents (see above) because it has to have practical value. Otherwise your API designers and implementing developers do not see much value in it. Yet a few higher level principles can be stated.

Postel’s law, or the Robustness principle, is essential in the evolution of APIs. No one can accurately anticipate how your requirements are going to change or how many different number and types of consumers you are going to have. Postel’s law, also known as the Robustness Principle, states, “be conservative in what you send and liberal in what you accept from others.”

The Adidas guideline defines some rules for extending APIs:

Various guideline sets recommend that APIs follow Postel’s law and the rules for compatible extensions in order to avoid versioning.

Another principle is the Principle of Least Astonishment, where Microsoft guidelines states that anything in violation of this principle is a breaking change. The Principle of Least Astonishment states that the result of performing some operation should be obvious, consistent, and predictable, based upon the name of the operation and other clues.

But API Design guide is more than just desing and implementation guide.

Guide lines for API and design management

Design guide is strategic document. It is not just the API details it defines. It is has been found in API Design Guide analysis that API versioning is often included. That in turn creates requirements for your API management and development processes. Versioning rules also affect the designer’s work very profoundly. Based on the rules they decide if certain feature is going to be added to current or next version. That is a big decision since new API (major) versions don’t often roll out weekly or even monthly. Keep in mind that you want to avoid versioning as much as possible.

Business is connected as well

Rate limiting is business model related. Although customer plan rate limiting values are not defined in API Design Guide, it defines the boundaries and format for what is possible. In that sense API Design guide is also connected to your companies business/product strategy. Introducing and enforcing API Design Guide is a sign of preparing for strategic usage of APIs in architecture and business.

Who should maintain and enforce the Design Guide?

In our case at Platform of Trust UX/DX team is responsible and owner of API designs. They maintain the guide as well. Of course they listen and discuss with the developers all the time, so some of the changes come from the developers.

he release of API or new version of existing API is in the hands of the UX/DX team, so they are the final gatekeepers to ensure that API follows the guide lines. Our Guide lines are defined in Gitbook, which enables anyone to define and commit pull requests.

Some more to read from 100 Days DX