API guidelines, the lifeline when designing of APIs

In my last post, I talked about why designing APIs is a lot of work and can’t just be done on the fly. API guidelines can be a lifeline for the design of APIs.

The team that we met already last time has now completed the API for the ERP solution in another sprint according to the requirements of the consumers. In the latest sprint, they now have to create another API. This is to enrich the existing API with data from an API that was developed by another team. Such an API is also often described as a third-party API. When comparing their own API with the other one, the team finds that the API definitions are already very different with regard to the use of the OpenAPI specification. When asked, the other team explains that they have defined guidelines as a team, the so-called API guidelines, in order to standardize the design of APIs and to make them verifiable and testable on the basis of the set of rules. In a first step, the guidelines are now copied by our team to be applied immediately. We will later discuss whether this was a good idea.

Design needs rules

Every design, whether analog or digital, is based on rules. These rules are used to provide answers to questions in the design process at any time, in order to always deliver the same quality and value. In the context of APIs, the rules in large organizations also help to ensure consistency with regard to topics such as compliance and governance. As a reader, you are probably wondering what would happen if APIs were created without a common set of rules. First of all, it will lead to an inconsistent design that will create more confusion than it makes sense. Also, similar concepts will be represented in different ways in the design. Furthermore, sooner or later there will be gaps in the documentation. When we combine these rules, guidelines are created. These guidelines always fit the organization as a whole.

Do not copy, but adapt

For this reason, rules should not simply be copied. Because rules or guidelines are created by experience and are subject to a high degree of adaptation especially at the beginning. This means that one can be inspired by the leading API-first companies in order to then transfer this rule to one’s own organization and live it in practice. I would like to support this with an example. Using the HTTP error code 429 (Too Many Requests) only makes sense if it is planned to use rate limiting, a control mechanism for incoming and outgoing data traffic for APIs that are planned in the organization. Otherwise, specifying this error code confuses more than it actually creates value.

Written down is fine, but not effective

Establishing guidelines for day-to-day development in an organization, or at least in parts of it, is a good step in the right direction. From practical experience, we know that written rules can only be checked in an implementation with great effort. Therefore, it is now necessary to transform the written rules into verifiable rule sets. In the case of APIs, this is a simple task with the appropriate tools. When we write API definitions, we are very concerned that they fit the version of the OpenAPI specification. We can check this with validation against the respective schema. Under https://openapi.tools/#description-validators we find a list of corresponding tools and frameworks in the various programming languages. With the tools redocly-cli and Spectral we can adapt the standard validations to the respective needs of the organization or the teams with the help of rule(sets), functions and plug-ins. Both products use a combination of YAML and JavaScript to write the extensions. I would now like to give you a short example of a written rule with Spectral to illustrate the whole thing a little.

formats:
    - oas3.0
extends:
    - 'spectral:oas'
rules:
    set-x-amazon-integration:
      description: x-amazon-integration must be set.
      message: x-amazon-integration is missing
      given: $.path[*]
      then:
        field: x-amazon-integration
        function: truthy

The OpenAPI extension x-amazon-integration will be checked to see if it is present in the paths object. This is just one of many examples that turn rigid API guidelines into testable rule sets. There are extensions for editors such as Visual Studio Code for both redocly-cli and Spectral, so that the validation becomes part of the writing process, the so-called linting, because a check takes place directly in the editor.

Rule sets as part of testing

And from the check in the editor, it is not far to validation becoming a part of Continuous Integration within a build or deploy pipeline. And this is also, among other things, where API guidelines become a lifeline for API design. This ensures that a very consistent API design develops over time, which also helps the consumers of the APIs in particular to understand and use them.