Best Practices for API Design Guidelines

Creating API design guidelines is a common practice for many enterprises. The goal? Ensuring that all teams involved in API development will adhere to them. However, this goal is often not achieved, as developers may not take the time to read, study, and apply these guidelines.

To address this issue, API design guidelines should be seen as the foundation to create high-level tools and services that enable developers to focus more on business logic and less on API integration boilerplate. These tools and services should be offered as self-service artifacts that automate low-level and non-value-add activities, thereby enabling developers to be more productive.

What are API design guidelines?

The API design guidelines are a collection of API design patterns and principles that all API teams within an organization should adhere to when developing APIs. The definition and implementation of API design guidelines are among the most influential drivers of an API strategy — fostering a consistent approach to the creation of an API platform across the enterprise.

At the highest level, there are three main sections you should cover in an API design guidelines document:

• General guidelines are independent of the particular style chosen to implement the API.
• Style-specific guidelines for REST, GraphQL, gRPC, and other styles.
• Governance guidelines to explain how the overall API design guidelines document should be updated.

General API Design Best Practices

This section describes the rules and recommendations that have to be followed along the entire API lifecycle of any API regardless of the implementation style. The principles we recommend in this section are the following:

• API first. Start always designing the API contract in close collaboration with your stakeholders. It is imperative to get the contract right if we want stable and long-lasting APIs.
• Don't break your clients. No matter what API style you chose, any modifications must maintain backward compatibility and avoid breaking changes.
• Security by design. Be clear on security expectations for all APIs. You should cover topics like authentication, authorization, access control, HTTP Headers, session management, validations, CORS, TLS ciphers, certificates management, and penetration testing. The OWASP API security project is an excellent resource for topics to cover in this area.

API Style Specific Best Practices

This is where you'll provide guidelines for specific API styles. (RESTful APIs are the most popular.) But irrespective of the style, what topics should be covered? Here's a list of the guidelines you may find most relevant:

• • API specification. All API contracts should be described following an API specification format. Use this section to specify which one should be used: OpenAPI, AsyncAPI, or others.
  • APIOps. As part of a platform enablement function, you may want to provide guidelines on tools to use for certain steps of the APIOps pipeline: CI/CD toolchain, git repository layout, testing framework, etc.
  • Protocol management. Define the criteria for using HTTP vs HTTPS, how to define URIs, and how to use protocol methods, status codes, headers, and other metadata.
  • Message formats. There are many message formats available for APIs. XML, JSON, or YAML are some of the most common text formats, but there are also binary formats and some specialized formats, like the ones used to report problems. Which ones should be used in your organization and under what circumstances?

• Data types. How you represent common data types such as date and time, language codes, country codes or currencies should be a no-brainer.

• Common operations. Almost all non-trivial APIs will offer features like pagination, search, long-running tasks, batch operations, query requests with many parameters, localization, or rate-limiting. It's important that all APIs offer those features in a consistent manner. The potential to cache responses and excel in performance optimization is directly related to consistency in common operations.

• Evolution (versioning). How to deal with changes in a way that is backward compatible is essential. (Remember the "don't break your clients" principle?) This is the section in which to talk about how to design URIs, naming conventions, and how to deal with changes and transition from old to new versions.

API Design and Governance Best Practices

The API design guidelines is a living document that should be evolved and enriched with feedback from all stakeholders impacted by it.

Corporations typically set up institutions to channel the feedback and evolve the guidelines accordingly. Some call it the API guild; others the API community of practice. Irrespective of the name you chose, make sure to explain what is the governance process to modify and evolve the guidelines, and how ownership should be assigned to the services and tools derived from the guidelines.

There are many good API design guidelines that you can use as real-world examples. Use them as a starting point to develop your own set.

Who's going to benefit from API design guidelines?

Many stakeholders will benefit from having an API platform developed following the same set of API design guidelines. Let's take a look at how API consumers, API producers, the security operations center, and enterprise architecture benefit from a coherent set of guidelines applied across all APIs.

API consumers: I want a consistent and intuitive experience

All users want to interact with an intuitive interface. The same is true for APIs. The community of software developers that will use your APIs expect an intuitive and consistent experience.

API consumers expect all your APIs to look like they have been developed by the same person — all usage patterns should be consistent across your APIs. The less they have to learn, the more they will adopt your APIs. The following are some of the guidelines that contribute to a consistent and intuitive API developer experience:

• The principle of "don't break your clients" gives API consumers the peace of mind that their integrations will not break and changes in the API contract will be backward compatible.
• Standardizing on message formats, data types, and common operations offers a consistent interaction style that can be learned once and used many times across all APIs.

API producers: Tell me best practices for common use cases

API producers want to focus as much as possible on business logic, not on API boilerplate. They shouldn't invest time in thinking about how to solve common API interaction scenarios (e.g., How to deal with pagination? How should we expose batch operations? What is the message format when returning an error message? What security elements should be incorporated in the design?)

Not all developers are API experts, so these topics — and many others — must be clarified in the API design guidelines.

Security operations center: Make APIs secure by design

The more we standardize how security concerns should be addressed in our APIs, the easier to validate that security standards are applied during implementation time and audited at runtime. Many of the OWASP API top 10 threats will benefit from clear security-related API design guidelines around authentication, authorization, rate-limiting, TLS enforcement, query parameters management, and message format specification.

Enterprise architecture: All APIs follow our design guidelines

Governance is an essential part of an API strategy. Establishing an API community of practice aids in discussing and evolving the organization's API design guidelines. This approach makes creating and evolving API design guidelines an inclusive process that improves the acceptance and commitment from all stakeholders. It will help as well in assigning ownership to the artifacts and services that will derive from the design guidelines.

Who is going to read our API design guidelines?

Forcing everyone in the organization to read the API design guidelines document and mandate that all APIs have to follow them is probably not the best strategy.

We need to enable the developers — not force them. APIs will only be developed "the right way" if that's the easiest way to do it. More than being a document that everyone should read and study, API guidelines are there to guide the creation of artifacts that will enable the API community to focus on value add work. Those artifacts take many shapes and forms. Let's take a look at some of them.

Software development kits (SDK)

Many of the elements that shape your API design guidelines can be materialized in an SDK that you provide to API clients. The SDK offers high-level use cases and takes care of translating those calls to the right message formats, data types, and common operations as specified in the guidelines. Hence, you offer your clients a fast path to value with a use-case-driven interface and at the same time make sure that low-level interactions are conformant to the design guidelines

Templates and sample code

Another productivity booster for API clients and API producers is to offer templates and sample code that are guidelines conformant. Those templates can be source code in different programming languages or OpenAPI specification fragments. Few things are more clarifying than good examples of how the guidelines should be applied in real-world scenarios. You can even go one step further and create IDE extensions for popular development environments to provide project templates and code fragments to bootstrap API development.

Golden images and hardening

One way to make sure about security adherence in API management is to create golden images for API gateway infrastructure and API implementations that are conformant with the security and hardening guidelines. By storing those images in artifact repositories and distributing them to API teams, you make sure that security guidelines are enforced during the API lifecycle.

Identity and access setup

Another essential element of security compliance is making sure that identity and access management are enforced for all API calls. The API guidelines should provide the criteria by which identity provider solutions are selected and deployed in the API landscape. API gateways can already be pre-configured with the relevant authentication and authorization plugins, and distributed as a golden image.

Linting and APIOps

API guidelines specifications around protocol management, message formats, or data types can be validated in APIOps pipelines by using linting rules in a format like spectral.

API guidelines should dictate what rules to validate to ensure that APIs deployed are conformant to the guidelines. But linting is just one step of a full APIOps pipeline. Providing git repository templates with a pre-defined pipeline setup that can be later customized and expanded is a great help to API teams. The API design guidelines should explain what is the rationale behind the pipeline structure and how teams are expected to use it.

Conclusion

API design guidelines are a core element of an API strategy. Based on the API principles and patterns outlined, the API community will be able to derive a set of tools and services that will be used to promote a consistent approach to building an API platform across the enterprise. With the right governance structure in place, all stakeholders will feel represented and committed to creating and evolving the guidelines.