10 quick tips to instantly improve API design
Tags: api, webdev, programming, restapi
Published: 2023-09-17 05:14:13

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.

![what-is-an-API?](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/8zq4wvxoiqwhvy7f25ic.png)

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