What are the minimum standards that every REST service should comply with?
This is important to architects because… architects are responsible for design, especially for integration, and RESTful services are the key mechanism for system integration.
REST services should support all CRUD operations with HTTP verbs. This is best illustrated through example as in the chart below
Use Nouns but no Verbs
Referencing the chart above, we can see that only nouns are used. Verbs are not necessary. For instance, it is not necessary to support resources like
Use Plural Nouns Only
Do not mix up singular and plural nouns. Keep it simple and use only plural nouns for all resources. Referencing the chart above, we could have used the noun “grocery”, but we had no reason to do so.
Use Subresources for Relations
If a resource is related to another resource, use subresources. Two examples are below.
GET /groceries/12345/suppliers returns a list of suppliers for grocery #12345
GET /groceries/12345/suppliers/4 returns supplier #4 for grocery #12345
Hypertext as the Engine of Application State is a principle that hypertext links should be used to create a better navigation through the API. Additional details are beyond the scope of this document.
Provide Filtering for Collections
Use a unique query parameter for all fields or a query language for filtering.
GET /groceries?dept=dairy returns a list of all groceries in the dairy department
GET /groceries?price=>1.00 returns a list of all grocery items that cost more than a dollar
Provide Sorting for Collections
Allow ascending a descending sort over multiple fields.
GET /groceries?sort=+dept,-price returns a list of groceries with ascending sort by department followed by a descending sort by price.
Provide Field Selection for Collections
Mobile applications display just a few attributes in a list. They don’t need all the attributes of a resource. Consequently, we want to give the API consumer the ability to choose returned fields. This will also reduce the network traffic and speed up the usage of the API.
Provide Paging for Collections
Use limit and offset. It is flexible for the user and common in leading databases. The default should be limit=20 and offset=0.
Version the APIs
All APIs must be versioned. We will use simple ordinal numbers and avoid dot notation such as v2.5.
The version should always start with the letter “v” as in the following example.
Handle Errors with HTTP Status Codes
The following HTTP status codes should be used to indicate errors.
200 – OK – Everything is working.
201 – OK – New resource has been created.
204 – OK – The resource was successfully deleted.
304 – Not modified – The request can use cached data.
400 – Bad request – The request was not valid or cannot be served. The exact error should be explained in the error payload, for instance, “The JSON Is not valid”.
401 – Unauthorized – The request requires a user authentication.
403 – Forbidden – The server understood the request, but is refusing it or the access is not allowed.
404 – Not found – There is no resource behind the URI.
405 – Method not allowed – The method is not supported.
422 – Unprocessable entity – Should be used if the server cannot process the entity, for instance if an image cannot be formatted or mandatory fields are missing in the payload.
500 – Internal Server Error – API developers must avoid this error. It is reserved for vendor infrastructure components. If an exception occurs and is caught, it should be logged along with the stack trace and not returned in the response.
Your REST services should all support the following best practices.
(1) Support CRUD operations
(2) Use nouns, but not verbs for resource naming
(3) Use plural nouns only
(4) Use subresources for relations
(5) Use HATEOS
(6) Provide filtering for collections
(7) Provide sorting for collections
(8) Provide field selection for collections
(9) Provide paging for collections
(10) Version the APIs.
(11) Handle errors with HTTP status codes