January 12, 2022

API Design Patterns and Best Practices

These resources are mostly specific to RESTful API design. However, many of the principles, such as pagination and security, can be applied to GraphQL also.

General Best Practices

These are list of articles or api-guide covers general best practices. Then in each section below, we’ll cover each topic in more depth.

Resources and URI

Tying back to the original constraint of Uniform interface & resource identification in requests, below are the articles and api-guide on how this principle is practiced.

Plural vs Singular Resource Names

CamelCase, Underscore, vs Hyphen

If a resource name is made up of multiple words, how to represent in the URI is often a subject of debate.

The consensus is to use hyphens.

HTTP Verbs

HTTP Verbs are also known as methods. Just resources are nouns, the HTTP verbs have semantic meaning also. It is easy to understand

GET vs POST

It is usually pretty clear when you should use GET vs POST, but when you need to send a request body, but you are not actually adding new entity, what method should you use?

There are some limitations with GET URL query parameters.

POST vs PUT vs PATCH

POST, PUT and PATCH all modify the state, therefore sometimes can be confusion which one to use.

Response Codes

Sometimes called HTTP Status Codes, the list of HTTP response codes all have semantic meaning. Therefore, they should be use effectively to communicate with the client.

Parameters to APIs

Many APIs have inputs, aka. parameters. There are so many ways to pass parameters to APIs: headers, query parameters, request bodies. This article below covers best practices for which one to chose.

REST API Best Practices for Parameters and Query String Usage

Schema Design

Envelope vs No Envelop Debate

The issue is whether you should wrap the data (especially collections) with another key in your response.

For example if you are getting a resource called books is it better to return an array within an object with key “books”.

{
    "books": [...]
}

or more directly, an unwrapped array of books:

[
    ...
]

There is a lot of debate, but generally no wrapper seems to be the better way.

Pagination, Filtering and Sorting

When you have collections of data, often you need provide the client a way to page through or order the elements. It isn’t as easy as it sounds. Different approaches have difference impacts on performance and database design.