API DESIGN PRINCIPLES
In this article, we will introduce some API design principles for everyone. Because as you can see that it is also quite simple to write APIs, but write an API so that it is reasonable, FrontEnd can call it easily, this is not a job. also do it.
Factors that determine good API quality
- Self-documenting: looking at the path of the API we can guess its intended use.
- Flexible: API extensibility.
- Unified structure and attribute names: Structural consistency for resources as well as naming properties.
- Clear error message: When the system has an error, there must be a clear message display to facilitate bug fixes.
API design principles
1. Use the HTTP method to describe the function of the resource:
We have 4 basic HTTP methods including POST, GET, PUT, DELETE. Each method will have a corresponding API function called CRUD (create, read, edit and delete). You can see the image below:
2. Use plural nouns and not verbs
We should name the path like this image below:
and should not put paths like this below:
/getAlICars
/createNewCar
/deleteAllRedCars
3. Use only plural nouns
We often have a habit of using both singular and plural nouns. And my advice for everyone is to use only plural nouns for all resources, examples below:
/cars instead of /car
/users instead of /user
/products instead of /product
/settings instead of /setting
4. Links in resources
Usually we will have a lot of related resources and the design of the linkage for those resources is a very headache for developers.
Suppose we have 2 resources: cars and users. Now we need to get all vehicles of a particular user, we will have the following API:
GET / users / 123 / cars
Now we need to see the detailed information of a specific vehicle of user 123, we will have 2 ways as follows:
GET / users / 123 / cars / 5 (get information of car 5 of user 123)
GET / cars / 5 (get information of 5 car)
Depending on the business, two resources will have different or the same response.
Another note in the resource linking problem is that a resource is only linked up to 2 objects, the linking of too many objects will make the resource confusing.
GET / users / 1 / posts / 5 / comments / 10
As the above example, we will get comment 10 on post 5 of user 1 this API will become more complicated for us at use.
Tip: For APIs querying filter data with many parameters, the following syntax can be used:
/users/1/filter?properties.post=5&properties.comment=10
Built-in simple query conditionals include the following components:
neq: not equal
gt: larger
gte: greater than equal
lt: smaller
lte: less than equal
print: included in
not_in: not in
5. Versioning
Versioning is a must for all resources, resource versioning follows two principles:
Start with “v” and end with a positive integer, avoid decimals (use v1 instead of v1.5)
Versioning will be placed in the first position of the resource
For example:
GET / v1 / users / 1 instead of GET /users/v1.5/1
6. Name the attributes
We will see three examples below:
“created_at”: “Thu Nov 03 05:19;38 +0000 2011”
“DateTime”: “2011-10-29T09:35:00Z”
“createdAt”: 1320296464
We can see 3 different forms. Here we will not talk about the right way or the wrong way, but each team will choose their own way and follow that writing for the whole project.
In addition, we should also pay attention to unifying a noun for a particular attribute. There are many people who mistake the mistake of using many different nouns to talk about the same attribute (“user_id” and “user” are used together when you want to get “user_id” or “from_date” and “from” are used together when you want to get “from_date”)
In summary, follow the following 2 principles:
Agree a convention type.
Agree on how to name the same attribute.
7. Pagination
See how to get 25 elements from the 50th position of the following 3 systems:
Facebook: offset 50 and limit 25
Twitter: page 3 and rpp 25 (records per page)
LinkedIn: start 50 and count 25
In this case, we tend to use facebook because it is intuitive and easier to understand. In addition, those who have coded the database, the concept of “limit” and “offset” is not a new concept.
8. Search
Rule: attribute name is “q” (query)
Global search:
GET / search? Q = fluffy + fur
Scope search:
GET / users / 123 / cars? Q = fluffy + fur
9. Select the return field
In some cases, the client will not need the complete information of an object. For example, the mobile version will not get all the information of the user like the web version. So we need a resource that is capable of customizing the returned fields. This increases performance on the client side.
- GET /users?fields=id,name,address
10. Format the return data
For resources that support multiple data return formats, the HTTP-Header will be the place to define that format.
Content-Type: Declare request format
Accept: Declare response format
11. HTTP status code and error message
The HTTP standard gives us a lot of status codes. We won’t need to know everything but at least know the status codes:
200 OK – This is most commonly used HTTP code to show that the operation performed is successful.
201 CREATED – This can be used when you use POST method to create a new resource.
202 ACCEPTED – This can be used to acknowledge the request sent to the server.
400 BAD REQUEST – This can be used when client side input validation fails.
401 UNAUTHORIZED / 403 FORBIDDEN – This can be used if the user or the system is not authorised to perform certain operation.
404 NOT FOUND – This can be used if you are looking for certain resource and it is not available in the system.
500 INTERNAL SERVER ERROR – This should never be thrown explicitly but might occur if the system fails.
502 BAD GATEWAY – This can be used if server received an invalid response from the upstream server.
For error messages returned when an error occurs, it should be easy to understand for both the user, client developer and backend developer. Basically we will have 3 returned messages serving 3 different objects:
- user message (the message returned to the user)
- internal message (the message returned to the backend developer)
- code (message returned to client developer)
A fully requested message would look like this:
Author: Quan Nguyen
Translator: Sosene
If you are looking for a APIs design and development company that provides solutions for your business, we are happy to offer our services. Contact the experts of Sosene Software for any questions on mobile application development!
Email: sales@sosene.asia
