DEV Community

Sean Overton
Sean Overton

Posted on • Updated on

10 quick tips to instantly improve API design

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.


2. A plural noun should be used for collection/store names.


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.

4. CRUD function names should not be used in URIs.

eg. Code smell:

Instead this should be the same endpoint and the correct http methods should be used:

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):


"id" : 1234,
"message": "Some error occured"
Enter fullscreen mode Exit fullscreen mode

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 (, 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:

Top comments (2)

erikwhiting88 profile image

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.

s3an_0vert0n profile image
Sean Overton

So true, thanks for sharing!