9 practical tips for better API design

In many cases, when designing APIs for the project, developers do not care much about the design of the design structure, its concept and scalability.

But in the long run, as the project grows bigger, this will cause problems.
Suppose it’s time to share written APIs for users to use them. How can you make sure they see exactly what you are looking for? This applies not only to users but also to developers who intend to develop the APIs written by you. Therefore, it is necessary to choose a proper design pattern at the beginning of the API construction so that all individuals (users and developers) can follow it.

In this article, we will examine a few practical tips for the development of these APIs.

1. Use http methods to give meaning to endpoints:

REST API encourages us to use HTTP methods to build any of the CRUD operations. Among these methods, such as Get, Post, Put, Patch, Delete gives a special meaning to our Endpoints, for example that this endpoint is related to building a new entity or deleting a pre -made entity. Also, using these methods no longer need to specify the operation when defining the name for endpoints. The following example illustrates the benefits of using these methods.

- GET /get_cats
- POST /insert_cats
- PUT /modify_cats
- DELETE /delete_cats
+ GET /cats
+ POST /cats
+ PUT /cats
+ DELETE /cats

9 practical tips for better API design

2. Use Status Codes for HTTP Based on the result of the request:

One of the most important things in the design of APIs is the proper use of the Status Code based on the result of the request. This means that when the operation is successful or faced with error, it can be conveyed to the user using Status Codes.
For example, if we receive 200 as a Status Code, it can be understood that the result of the requested operation was successful and if we get 400, the operation is faced with error.
Therefore, it is important to be familiar with different status codes and use each at the right time according to the outcome of the operation because otherwise it will confuse users and developers and in some cases make it improperly used. For example, the example is the proper and incorrect use of the Status Code below.

// Bad, we return status code 200 (Success)
// associated with an error object
{
    "status": 200,
   "error": {...}
}
// Good
{
    "status": 200,
    "data": [...]
}

3. Support Filter, Sort and Pagina:

In many cases it is necessary to limit the number of information received from the API. This limit can be for reasons such as improving the speed of operations, reducing the number of information received, searching for specific information, and so on.
Adding filter, Sort and Pagina, in addition to achieving their own specific use, can reduce pressure on the server.
For example, suppose we have millions of data in the database, but if the user requests all this information in one place, the server will certainly put a lot of pressure! But this problem will be resolved using Sort, Filter and Pagration structures. For example, these operations can be used as follows:

- GET /cats?page=2
- GET /cats?page=3&per_page=20
- GET /cats?page=2&sort=desc

4. Naming Endpoints as collectively:

Since resources usually do not have a data and most of the time they are collective, it is best to use collective name for endpoints.

- GET /cat
- GET /cat/:id
+ GET /cats
+ GET /cats/:id

5. Name Endpoints based on Resource:

If a Route carries an operational project on a particular Resource, it must be the name Endpoint related to the desired Resource. This will make the project consistent and orderly. Therefore, when a user or developer uses our APIs, he or she will notice the use of any Route. For example, if a Route is to perform CAT existence operations, it should not be defined as /dogs.

6. Use hierarchical routes for operations related to the relationship between entities:

Suppose there is a relationship between different entities in the project. For example, we will have two options if we want to get a list of inventory (eg Posts) for another (eg user). One is the use of hierarchical structure and the other is the use of query string:

GET /users/alireza/posts/post-about-api-design
GET /posts?user=alireza&name=post-about-api-design

These methods are used in various projects and the use of both methods is correct. The first method makes the Route structure better, but when the number of relationships is high, the first method will prolong the names of the paths and the second will perform better. It depends on which method is best to use.

7. Version of APIs:

As a developer, it is important to define APIs that are wrong and work properly. Suppose we have designed our API and put it on a server. Many users use these APIs. So what will happen if you need to change, add or reduce part of this API data? This will probably not be able to use your API. So you need to be copied for your API. There are various ways to version API, which can be mentioned, for example:

// URI versioning v[x] syntax
GET /v1/cats
GET /v2/dogs
GET /v3/birds

8. Use the Caching system:

One of the positive features of each API is its high response speed. Caching can be used to achieve it. This not only increases the speed of API response, but also reduces the pressure on the server. This will reduce the need to obtain a database to receive duplicate data. There are many services to do this, one of which is Redis.
This may increase the cost of maintaining APIs, but this is not a flaw! Because the cost of accessing database information may be more than the cost of caching. On the other hand, this can be improved by reducing the time of caching.

9. Documentation:

One of the best weapons and the most hated! Among the developers is documenting. API documentation is no exception, and one of the essentials in the design of the API is its documentation. By documenting users, they will be able to obtain information about the API, including the type of accessibility, the type of request and its information, the type of response and the Response, the examples and ….
• Access: One of the most important documentary features is how to access it. The best way to document is to make a documentary and present it on the Internet. This way all users will be able to view documentaries.
• Request and answer: The information in this section must specify the type and information in the request and answer.
• Examples: It will be very useful for users to use each of the APIs.

Conclusion

Keep in mind that the API is designed, the way users are connected to the service made by Backnd. In this case, we should be careful to follow the best principles so that users can easily use it. Even if you are developing a personal project, it is recommended to apply these principles in your project. Because the cost of maintaining and developing it in the future is reduced. This will also make you more practiced to participate in larger projects.

 

 

 

Important links

Contact

contact@aloapi.com

© 2022 Created with AloApi Team.