APIs are the backbone of a successful application architecture and REST APIs are the most popular way of creating web services.
Below is a concise list of best practices to use while designing REST APIs.
GET /api/v1/threads- to get a list of all threads
GET /api/v1/threads/14- get a single thread with id 14
POST /api/v1/threads- add a new thread to collection
PUT /api/v1/threads/14- update thread with id 14
DELETE /api/v1/threads/14- update thread with id 14
- Version is part of the endpoint
- This gives the possibility to support multiple live versions of the same API. E.g. Twitter has API versions 1.1 and 2.0 - both are live and accessible.
- Enables easy switching and rollback for consumers of the API
- HTTP response codes were created to describe the semantics of an API response.
- Return standard error codes and let the consumer handle the errors in their own way. Always include a message in your errors for troubleshooting purposes.
Plural nouns for collections and no verbs
E.g. "threads" is used instead of using verbs like /getThread, /updateThread
Resource nesting is visible in the endpoint
- Use TLS/SSL
- Use authentication and authorization to avoid malicious requests
- Set up rate limiting and caching to prevent against DoS attacks
Use caching(in-memory or CDN) to provide fast results for repeated GET requests
A good API has pagination and filtering capabilities to reduce the amount of data being transferred. Data transfer objects should not include unnecessary fields.
The least requirements of a method documentation - description, request parameters, response, error scenarios.
Definitely include request/response samples to provide the full picture.
Also check - https://swagger.io/specification/
My final suggestion is to make API designing process the starting point of your backend architecture and build other architectural components around it.
Thanks for reading.
I hope this was useful in providing a checklist of points to take care of while designing APIs.
If you want to connect with me, you can find me on Twitter