After recently reading "REST API design rulebook" by Mark Masse, I am writing to share a couple of quick take-aways for designing web API's.
Here are the 10 quick tips. Happy reading!
1. A singular noun should be used for document names.
eg. https://example-domain.com/blogs/my-blog
2. A plural noun should be used for collection/store names.
eg. https://example-domain.com/blogs
3. A verb or verb phrase should be used for controller names.
Controllers are endpoints that have a non-standard function outside of HTTP standard method types such as GET/POST/UPDATE/DELETE.
eg. https://example-domain.com/send-email
4. CRUD function names should not be used in URIs.
eg. Code smell:
https://example-domain.com/update-post/1234
or https://example-domain.com/delete-post/1234
Instead this should be the same endpoint and the correct http methods should be used:
PUT https://example-domain.com/posts/1234
DELETE https://example-domain.com/posts/1234
5. Query parameters are for either filtering or pagination:
eg. GET /posts?author=sean-overton
These should support a 'partial' or filtered JSON response where only required fields are returned.
6. Use appropriate HTTP methods for their expected functions.
Post = Create object /posts
Get = Retrieval /posts or /posts/1234
Put = Update Object in place /posts/1234
Delete = Delete's object in place eg. /posts/1234
Don't tunnel other request methods via GET/POST. This is a common code smell observed in junior API developers code.
eg. don't delete an entity with a GET request. Use the delete HTTP method.
7. Use response status codes appropriately. (so they can be handled appropriately in the client!)
100: Transfer protocol information
200: Okay/success responses
300: Redirects
400: Bad requests (client side error in request)
500: Server side errors (server side error occurs)
8. Use Http Headers with appropriate metadata defined.
eg. Content-Type: application/json (a required header!)
Note: These are occasionally abstracted away in frameworks with defaults but it is still recommended to test these for yourself and override when appropriate.
9. Use Cache-Control, Expires, and Date response headers.
This is to encourage caching which in turn should help improve performance. These fields can define time to live (TTL) for respective objects before they are required to be refected.
10. Errors should have a consistent form (JSON/XML schema):
eg.
{
"id" : 1234,
"message": "Some error occured"
}
This is so error's can be consistently handled in the frontend or client service.
Thanks for reading!
With the development of automatic code generation tools such OpenAPI generator (https://openapi-generator.tech/), the importance of API design rather than implementation is emphasized.
Follow me for more book reviews and quick tips I pick up along the way as I continue my book-per-week reading journey.
For my full reading list: https://github.com/SeanOverton/books-i-have-read/blob/main/books.yml
Top comments (2)
Great list, thanks for sharing! Another thing I try to think about when designing APIs is "will my user want to bookmark/save this URL somewhere?" For example, I have a few bookmarked GitHub searches; this is only possible because the filters I apply are query parameters in the URL, afaik, you can't bookmark request parameters.
So true, thanks for sharing!