In this article I tried to consolidate all the best practices for designing REST APIs. Note that all these results are based on my personal works after designing couple web API projects, and they are not official conventions that you should follow.
REST APIs use Uniform Resource Identifiers (URIs) to address resources.
HTTP request has its basic CRUD operations:
POST– Create a new record, submit an entityGET– Retrieve existing list of records or one recordPUT– Update/Replace existing a list of records, such as add/update some records to a list of resourceDELETE– Delete existing list of records or an entityPATCH– Modify partial data of an existing record (edit a record: edit a User)
URI Components
https://api.domain.com/namespace/v1/resource-name/collection?product_id=123&type=shoehttps://– Scheme, Protocolapi.domain.com– Domain name, DNS/namespace/resource-name/v1/collection– Path/namespace– Such as/api, or not necessary/v1– Version/resource-name– Resource category name, such as/product-management/collection– Specific resource name, or collection of resource, such as/products,/customersproduct_id=123&type=shoe– Query
Rules
- URI MUST be specified in all lower case
- Use hyphens
-to separate words or path parameters (no spaces or underscores_) - Use underscores
_to separate words in query parameter names but not as part of the base URI
Collection Resources
Rules
- Nouns MUST be used
- Resource names MUST be plural, or appropriate noun if resource is non-standard
- Resource names MUST be lower-case and hyphens
- Sub resource can use be under /resource-category-name
Examples:
/customers
/leaves
/fishes
/tree-nuts
/customer-management/types - under /customer-management
/customer-types - just use plural-nounsSingleton Resource
Rules
- Use Collection resource URI and identify a single resource by its id
- Further sub-resource by concatenating further path
- Filtering using query parameter
/customers/{customerId}
/customers/{customerId}/accounts/{accountId}
/customers?customer_type=use_this_type&sort=dateExamples:
// List of customers
GET /customers
// Filtering is a query:
GET /customers?year=2011&sort=desc
// Get one customer by ID
GET /customers/12345
// get a device by id
GET https://api.example.com/api/v2/device-management/managed-devices/123
// Get all orders of this customer
GET /customers/12345/orders
// filering
GET /customers/12345/orders?year=2011&type=shoe
// special resource
GET http://api.example.com/user-management/users/adminAction Resources
Rules
- Use Collection resource URI or Singleton resource URL
- Use HTTP request methods CRUD, to indicate actions
- Use Verb to denote Controller resources that are like executable functions
Examples:
// Add a new customer
POST /customers
// Update a customer
UPDATE /customers/12345
// Delete a customer
DELETE /customers/12345
// Add a new order to a customer
POST /customers/12345/orders
// Update a customer's order
UPDATE /customers/12345/orders/67890
// Action-only endpoints
POST http://api.example.com/cart-management/users/{id}/cart/checkout
POST http://api.example.com/song-management/users/{id}/playlist/play
Request/Response Message Format
For request and response body field names or query parameter names, the naming MUST be consistent, and SHOULD be either camelCase OR snake_case:
Examples:
{
// this_is_snake_case (use this)
"document_id" : 1837, // object id using int
"products": ["11","22"], // array using plural nouns
"is_student": true, // boolean
"has_candy": true, // boolean
}
{
// thisIsCamelCase
"documentId" : 1837
"products": ["11","22"]
}products– Fields that represent arrays SHOULD be named using plural nouns
Since SQL database is using snake_case normally, the data come back from DB is in snake_case and can be just send out, so using snake_case is a good choice.
Request Headers
Request Headers:
| Header | Default Value |
| Accept | application/json |
Response Convention
Status codes:
- 2xx, OK, request went well and response is sent
- 3xx, Resource was moved and then let client know it
- 4xx, Client request error, if the request cannot be fulfilled because of a client error (like requesting a resource that does not exist)
- 5xx, Server-side error, something wrong on the API side (like an exception happened)
