I'm a developer and for most of my career I've been building APIs for various services. The guidelines for this article have been compiled based on the most common problems when designing your own service as a team or using third-party APIs.
Chances are, you've come across terrible API providers. Working with them, as a rule, is associated with increased emotionality and misunderstanding. Most of these problems can be avoided by designing the application interface using the tips below.
1. Don't use verbs in URL *
* - if this is one of the CRUD operations.
The CRUD request methods are responsible for the action with the resource: POST - create (create), GET - get (read), PUT / PATH - update (update), DELETE - delete (you understand). Bad:
POST /users/{userId}/delete -
POST /bookings/{bookingId}/update -
Okay:
DELETE /users/{userId}
PUT /bookings/{bookingId}
2. Use verbs in the URL
Bad:
POST /users/{userId}/books/{bookId}/create -
Okay:
POST /users/{userId}/books/{bookId}/attach
POST /users/{userId}/notifications/send -
3. Highlight new entities
Above there is an example of adding a book to a user, perhaps the logic of your application implies a list of favorites, then the route may be like this:
POST /wishlist/{userId}/{bookId}
4. Use one resource ID *
* - if your data structure allows it.
This means if you have one-to-many records, for example,
booking -> travelers (booking-> travelers), it will be enough for you to pass the traveler ID in the request.
Bad:
#
GET /bookings/{bookingId}/travellers/{travellerId}
Okay:
GET /bookings/travellers/{travellerId}
I also note that /bookings/travellers/
it's better than just /travellers
sticking to the data hierarchy well in your API.
5.
:
GET /user/{userId} -
POST /ticket/{ticketId}/book -
:
GET /users/{userId}
POST /tickets/{ticketId}/book
6. HTTP-
- . . :
400 Bad Request - , , .
401 Unauthorized - .
403 Forbidden - , .
404 Not Found - .
409 Conflict - , .
500 Internal Server Error - .
503 Service Unavailable - .
7.
. , - (quizzes passed_quizzes). , .
: /quizzes
/quizzes/passed
. quizzes
- (), passed
- ().
:
GET /passed-quizzes -
GET /booked-tickets -
POST /gold-users -
:
GET /tickets/booked
POST /users/gold
8.
API - . , , .
:
GET /book/{bookId}
{
"name": "Harry Potter and the Philosopher's Stone",
"genre": "fantasy",
"status": 0, #
"error": false,
...
}
:
GET /book/{bookId}
{
"status": 0,
"message": "ok",
"data": {...}
}
3 . status
, message
- , , . , , . 409 status
message
.
9. json camelCase
9.1 In query parameters
Bad:
GET /users/{user-id}
GET /users/{user_id}
GET /users/{userid}
Okay:
GET /users/{userId}
POST /ticket/{ticketId}/gold
9.2 In the body of the response or received request
Bad:
{
"ID": "fb6ad842-bd8d-47dd-b7e1-68891d8abeec",
"Name": "soccer3000",
"provider_id": 1455,
"Created_At": "25.05.2020"
}
Okay:
{
"id": "fb6ad842-bd8d-47dd-b7e1-68891d8abeec",
"Name": "soccer3000",
"providerId": 1455,
"createdAt": "25.05.2020"
}
10. Use Content-Type
Bad:
GET /tickets.json
GET /tickets.xml
Okay:
GET /tickets
//
ontent-Type: application/json
//
ontent-Type: application/xml
Conclusion
The recommendations listed above are not the whole list of ways to make the API better. For further study, I recommend disassembling the REST API specifications and the list of http status codes (you will be surprised how many there are and what situations they cover).
And in the comments, I suggest writing your own recommendation for building a REST API that you consider important.