API design is the collection of planning and architectural decisions you make when building an API. Your basic API design influences how well developers are able to consume it and even how they use it. Just like website design or product design, API design informs the user experience. Good API design principles meet initial expectations and continue to behave consistently and predictably. Our API design guide assists in supporting this theme throughout your API design process. There is not a single approach on how to design a API or even how to design good APIs “the right way.” Instead, we need to lean on good industry basic API design guidelines, best practices and patterns where relevant, then take cues from those who will use our APIs.

How to Choose Your API Specification

Before you can communicate your API design, you need an artifact that someone else can use to understand your design & API guidelines. Historically, this might have been called documentation. While it’s still important to have human-facing documentation that is easy to use, more is required of modern APIs. In recent years the industry has rallied around the OpenAPI Specification. OpenAPI allows you to define how your REST API works, in a way that can be easily consumed by both humans and machines. It serves as a contract that specifies how a consumer can use the API and what responses you can expect. OpenAPI v3.0 was released in July, 2017, by the OpenAPI Initiative, a consortium of member companies who want to standardize how REST APIs are described. There are various other approaches to API description: - **OpenAPI v2**, (formerly known as Swagger v2.0) is still widely used, but increasingly being replaced by OpenAPI v3, - **JSON Schema**, very similar to OpenAPI, but able to describe any JSON-like data, not just APIs, - **API Blueprint** was created to foster collaboration between API design stakeholders, - **RAML**, the RESTful API Modeling Language, focuses on the planning stage of API design. While OpenAPI v3 is the way forward, each of these alternative formats has tooling associated. You may find yourself converting between them, especially OpenAPI v2, until the tools catch up.Your API design requires a way to define how the API will be used. The future-thinking approach is to select OpenAPI v3 to describe your API.

Why API Design-First Matters

Now that you’ve chosen OpenAPI v3, you may be tempted to set that aside until after you build your API, and "write the docs later." While it’s useful to describe existing APIs, you can also create API descriptions before and during writing the code. When you design your API alongside a description, you always have the artifact to communicate what’s possible with your API. The design-first approach offers a single source of truth, readable by collaborators and machines alike.

How to Design a REST API

The OpenAPI spec is focused on describing REST APIs. However, it’s still possible to describe an API that violates the RESTful principles. This section is not meant to be exhaustive, but will instead help you avoid the most common infringements in REST API design. Use HTTP methods to communicate action. While REST guidelines can be used outside of HTTP, they are so frequently used together that it’s safe to assume your API will operate over HTTP. This protocol, upon which the web is built, offers useful operations that should form the foundation of our APIs. Use nouns for resources and avoid anything that looks like procedure calls. There’s no need for endpoints like `/getContacts` when we’re using HTTP methods. Instead, your resource would be named `/contacts` and you could perform the GET action (and any others that are relevant) against that resource. You may find yourself in a debate about naming your resources. Should they be singular or plural? When there are multiple words in a resource name, should you use punctuation or capitalization to distinguish each word? The most important thing to choose is consistency. If you use one convention with one endpoint, choose the same with another endpoint. If possible, look to maintain this consistency between your APIs, as well. Use HTTP status codes to communicate errors and success. Just as the methods provide a solid foundation for how your API takes action, the standard status codes share the results of those actions. For example, never send a 200-level status code along with any error message. Both machines and humans will be confused.

API Design | API Design Guide & Designing API Best Practices