Gopher Academy

✅ 10 Best Practice for API Design

1. Use nouns instead of verbs
Verbs should not be used in endpoint paths. Instead, the pathname should contain the nouns that identify the object that the endpoint that we are accessing or altering belongs to.

For example, instead of using /getAllClients to fetch all clients, use /clients.

2. Use plural resource nouns
Try to use the plural form for resource nouns, because this fits all types of endpoints.

For example, instead of using /employee/:id/, use /employees/:id/.

3. Be consistent
When we say to be consistent, this means to be predictable. When we have one endpoint defined, others should behave in the same way. So, use the same case for resources, the same auth methods for all endpoints, use the same headers, use the same status codes, etc.

4. Keep it simple
We should make naming all endpoints to be resource-oriented, as they are. If we want to define an API for users, we would define it as:

/users
/users/124

So, the first API gets all users and the second one gets a specific user.

5. User proper status codes
This one is super important. There are many HTTP status codes, but we usually use just some of them. Don't use too many, but use the same status codes for the same outcomes across the API, e.g.,

200 for general success.
201 for successful creation.
202 for successful request.
204 for no content.
307 for redirected content.
400 for bad requests.
401 for unauthorized requests.
403 for missing permissions.
404 for missing resources.
5xx for internal errors.

6. Don’t return plain text
REST APIs should accept JSON for request payload and also respond with JSON because it is a standard for transferring data. Yet, it is not enough just to return a body with JSON-formatted string, we need to specify a Content-Type header too to be application/json. The only exception is if we’re trying to send and receive files between the client and server.

7. Do proper error handling
Here we want to eliminate any confusion when an error occurs, so we need to handle errors properly and return a response code that indicates what error happened (from 400 to 5xx errors). Along with a status code we need to return some details in the response body.

8. Have good security practices
We want that all communication between a client and a server is protected, which means that we need to use SSL/TLS all the time, with no exceptions. Also, allow auth via API keys, which should be passed using a custom HTTP header, with an expiration day.

9. Use pagination
Use pagination if our API needs to return a lot of data, as this will make our API future-proof. Use page and page_size is recommended here.

For example, /products?page=10&page_size=20

10. Versioning
It is very important to version APIs from the first version, as there could be different users for our APIs. This will allow our users not to be affected by changes that we can do in the future. API versions can be passed through HTTP headers or query/path params.

For example, /products/v1/4

➖➖➖➖➖➖➖➖
🕊 @gopher_academy

👍5❤3🕊1

970 viewsJavad, 17:16