Best Practices in API Design

APIs are a fundamental part of software developers' and engineers' routine. Using or creating REST APIs is probably the most common case. It is basically an interface that different systems use to exchange information. The picture shows the basic principles of REST API.

If the REST API is not properly built, you’ll get error codes, long response time, etc. 

To build a well-defined API, make sure you try to follow best technical and semantic practices. I’ve gone through great posts of experts like Dr Milan Milanović , blogs and my colleagues advice so you won’t have to. 

1. Use nouns instead of verbs, make it short

Don’t use verbs in endpoint paths as it’s not intuitive from the REST perspective. Instead, the pathname should contain the nouns that identify the object.

This looks strange:

GET /getAllClients

GET /getClientWithId

POST /createClient

This is right to do:

GET /clients

GET /clients/123

POST /clients

Also, use the plural form for resource nouns to fit all types of endpoints. The example: use /𝚎𝚖𝚙𝚕𝚘𝚢𝚎𝚎𝚜/:𝚒𝚍/ instead of /𝚎𝚖𝚙𝚕𝚘𝚢𝚎𝚎/:𝚒𝚍/. Apply this to other endpoints like resources, same auth methods, status codes, etc. 

2. Be consistent with HTTP status codes, general API structure, accepted best practices

Be predictable in your code. What is meant under that: 

• use the same general endpoint structure
• use GETs to get data 
• use PUTs/POSTs to change data.
• pick a few status codes and use it correctly and consistently throughout API

3. Use proper status codes 

Many and more HTTP status codes are essential to know. However, not all of them are used  often. There are standard ones that are familiar for everyone. 

- 200 for general success

- 201 for successful creation

- 400 for bad requests

- 401 for unauthorized requests

- 403 for missing permissions

- 404 for missing resources

- 5xx for internal errors

You can find many visuals and tables online to check it out. I came across the one on Github. 

4. KISS 

I love this one 😄 Keep It Simple, Stupid. The idea is to be resource-oriented. To define APIs for users:  

/𝚞𝚜𝚎𝚛𝚜 - gets all users

/𝚞𝚜𝚎𝚛𝚜/𝟷𝟸𝟺 - for a specific user

Also, don’t expose more that needs exposing in your business. If you have internal objects not useful for clients, don’t return them. 

5. Handle errors properly 

The key things that should happen: we need to return a response code that indicates what error happened (see 3). Along with a status code we need to return some details in the response body. That’s how clients know what to resolve. The example would be if a client sends a request with incorrect credentials, we can send a 401 response with this body:

White House Web API Standards include even more: a common HTTP status code, message for the developer, message for the end-user (when appropriate), internal error code (corresponding to some specific internally determined ID), links where developers can find more info. 

6. Take care of versioning before you grow

You’ll probably need to do a few versions of your API, so that different users can access APIs. If you have only one, users will be affected by changes in the future. Maintain at least one previous version and always release properly named versions (like v1, v2, v3)

7. Use async/await if possible 

This will help you handle requests more quickly. Synchronous requests will take a thread and release it only after the request is finished. Using the async GET will release the threads as other systems (such as a database call) are doing the work.

8. Use pagination

Often when you are making calls to the API, there are a lot of results to return. To handle it and make sure API won’t get outdated, use pagination. Use page and page_size is recommended here. 

E.g., /𝚙𝚛𝚘𝚍𝚞𝚌𝚝𝚜?𝚙𝚊𝚐𝚎=𝟷0 & 𝚙𝚊𝚐𝚎_𝚜𝚒𝚣𝚎=𝟸0

Even better advice is to set the limit parameter to ensure you know how many results per page you'll get. It might be a built-in default but these defaults are different. 

9. Accept and respond with JSON

JSON is the standard for transferring data and is supported by most server-side technologies. The other way to transfer data is XML but it’s not widely supported by frameworks. To make sure that when our REST API app responds with JSON that clients interpret it as such, we should set Content-Type in the response header to application/json after the request is made. Many server-side app frameworks set the response header automatically. 

10. Document-document-document APIs

I don’t know why it’s tenth, it probably should be one of the top ones. Documentation makes life easier and developers grateful. The files with docs should show examples of complete request/response cycles. Make sure to include information about the services offered by the API, how to use its different parameters and endpoints, and other instructions about the implementation of the API.

11. Follow Good Security Practices

Using SSL/TLS for security is a must in this day and age. A SSL certificate isn’t too difficult to load onto a server and not costly. Moreover, giving appropriate access is fundamental. For example, a normal user shouldn’t be able to get information of another user. They also shouldn’t be able to access data of admins. One more security practice is to allow auth via API keys, which should be passed using a custom HTTP header, with an expiration day. 

It was a lot but we covered the basics. I think 😄 Would love to hear your additions to make the most complete list of tips on best practices in API design 🖋️