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


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, 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.

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.

Nested or Sub Resources

When should you use nested resources (aka sub resources)? What are the down sides?


Cross Origin Resource Sharing is needed if you setup an open API, but there are some pitfalls.

Design Tools


Learn More About Moesif Get Insights Into How Customers Use Your Platform 14 day free trial. No credit card required. Learn More
Build Better API Products With Moesif Build Better API Products With Moesif

Build Better API Products With Moesif

Learn More