Je suis développeur et pendant la majeure partie de ma carrière, j'ai construit des API pour divers services. Les instructions de cet article ont été compilées en fonction des problèmes les plus courants lors de la conception de votre propre service en équipe ou de l'utilisation d'API tierces.
Il y a de fortes chances que vous ayez rencontré de terribles fournisseurs d'API. Travailler avec eux, en règle générale, est associé à une émotivité accrue et à un malentendu. La plupart de ces problèmes peuvent être évités en concevant l'interface de l'application à l'aide des conseils ci-dessous.
1. N'utilisez pas de verbes dans l'URL *
* - s'il s'agit de l'une des opérations CRUD.
Les méthodes de requête CRUD sont responsables de l'action avec la ressource: POST - créer (créer), GET - obtenir (lire), PUT / PATH - mettre à jour (mettre à jour), DELETE - supprimer (vous comprenez). Mal:
POST /users/{userId}/delete -
POST /bookings/{bookingId}/update -
D'accord:
DELETE /users/{userId}
PUT /bookings/{bookingId}
2. Utilisez des verbes dans l'URL
Mal:
POST /users/{userId}/books/{bookId}/create -
D'accord:
POST /users/{userId}/books/{bookId}/attach
POST /users/{userId}/notifications/send -
3. Mettre en évidence les nouvelles entités
Ci-dessus, il y a un exemple d'ajout d'un livre à un utilisateur, peut-être que la logique de votre application implique une liste de favoris, alors l'itinéraire peut être comme ceci:
POST /wishlist/{userId}/{bookId}
4. Utilisez un ID de ressource *
* - si votre structure de données le permet.
Cela signifie que si vous avez des enregistrements un-à-plusieurs, par exemple,
réservation -> voyageurs (réservation-> voyageurs), il vous suffira de transmettre l'identifiant de voyageur dans la demande.
Mal:
#
GET /bookings/{bookingId}/travellers/{travellerId}
D'accord:
GET /bookings/travellers/{travellerId}
Je note également que /bookings/travellers/
c'est mieux que de bien /travellers
s'en tenir à la hiérarchie des données dans votre 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 Dans les paramètres de requête
Mauvais:
GET /users/{user-id}
GET /users/{user_id}
GET /users/{userid}
D'accord:
GET /users/{userId}
POST /ticket/{ticketId}/gold
9.2 Dans le corps de la réponse ou de la demande reçue
Mauvais:
{
"ID": "fb6ad842-bd8d-47dd-b7e1-68891d8abeec",
"Name": "soccer3000",
"provider_id": 1455,
"Created_At": "25.05.2020"
}
D'accord:
{
"id": "fb6ad842-bd8d-47dd-b7e1-68891d8abeec",
"Name": "soccer3000",
"providerId": 1455,
"createdAt": "25.05.2020"
}
10. Utilisez Content-Type
Mal:
GET /tickets.json
GET /tickets.xml
D'accord:
GET /tickets
//
ontent-Type: application/json
//
ontent-Type: application/xml
Conclusion
Les recommandations énumérées ci-dessus ne constituent pas la liste complète des moyens d'améliorer l'API. Pour une étude plus approfondie, je vous recommande d'analyser les spécifications de l'API REST et la liste des codes de statut http (vous serez surpris de savoir combien il y en a et quelles situations ils couvrent).
Et dans les commentaires, je suggère d'écrire votre propre recommandation pour créer une API REST que vous considérez comme importante.