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.
- Be sure to check our get started guide on APIs
- RESTful API guidelines
- RESTful API best practices
- Principles of good RESTful API design
- REST Quick Tips
- Tips for API design from Microsoft Azure
- A slide deck on Design patterns that are up to debate
- Best practices for a pragmatic RESTful API
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.
- Resource Naming
- 7 rules for REST API URI design
- REST API resource design and modeling
- Nouns are good and verbs are bad
- How to design a REST API
Plural vs Singular Resource Names
- a StackOverflow debate on singular vs plural
- Arguments for using plural resource name
- Arguments for using singular resource name
- Singular and plural routes
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 are also known as methods. Just resources are nouns, the HTTP verbs have semantic meaning also. It is easy to understand
- The main 7 http verb or methods
- A nice table of when each method should be used
- Using HTTP methods in REST
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.
- A StackOverflow debate on HTTP Get with Request Body
- Elastic search uses POST for sending over search queries
- Decision by Dropbox to use POST instead of GET due to limitations of GET
- Maximum length of HTTP GET request
POST vs PUT vs PATCH
POST, PUT and PATCH all modify the state, therefore sometimes can be confusion which one to use.
- when to use PUT vs POST
- PUT vs PATCH with real life examples
- PUT vs PATCH vs JSON-PATCH
- Another example of PUT vs POST
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.
- Which HTTP Status Code to Use for every CRUD App
- Error Codes 101
- Best practices for response handling
- When result is empty: 404 or empty?
- A discussion how to handle empty results
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.
- Elegant APIs with JSON schema
- Understanding JSON schema
- Design consideration on JSON schema for an API
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”.
or more directly, an unwrapped array of books:
- A question asked regarding when should you use envelope
- This article argues for no envelope in a rather hilarious way
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.
- REST API design options and comparison for filtering, pagination and sorting
- Tips and tricks for pagination by a Square engineer
- RESTful API sorting dilemma
- Filter operator best practices question posted on StackOverflow
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.