Ich bin Entwickler und habe die meiste Zeit meiner Karriere APIs für verschiedene Dienste erstellt. Die Richtlinien für diesen Artikel wurden basierend auf den häufigsten Problemen beim Entwerfen Ihres eigenen Dienstes als Team oder beim Verwenden von APIs von Drittanbietern erstellt.
Wahrscheinlich sind Sie auf schreckliche API-Anbieter gestoßen. Die Arbeit mit ihnen ist in der Regel mit erhöhter Emotionalität und Missverständnissen verbunden. Die meisten dieser Probleme können vermieden werden, indem die Anwendungsoberfläche mithilfe der folgenden Tipps entworfen wird.
1. Verwenden Sie keine Verben in URL *
* - wenn dies eine der CRUD-Operationen ist.
Die CRUD-Anforderungsmethoden sind für die Aktion mit der Ressource verantwortlich: POST - Erstellen (Erstellen), GET - Abrufen (Lesen), PUT / PATH - Aktualisieren (Aktualisieren), LÖSCHEN - Löschen (Sie verstehen). Schlecht:
POST /users/{userId}/delete -
POST /bookings/{bookingId}/update -
Okay:
DELETE /users/{userId}
PUT /bookings/{bookingId}
2. Verwenden Sie Verben in der URL
Schlecht:
POST /users/{userId}/books/{bookId}/create -
Okay:
POST /users/{userId}/books/{bookId}/attach
POST /users/{userId}/notifications/send -
3. Markieren Sie neue Objekte
Oben finden Sie ein Beispiel für das Hinzufügen eines Buches zu einem Benutzer. Möglicherweise impliziert die Logik Ihrer Anwendung eine Liste mit Favoriten. Dann kann die Route folgendermaßen aussehen:
POST /wishlist/{userId}/{bookId}
4. Verwenden Sie eine Ressourcen-ID *
* - wenn Ihre Datenstruktur dies zulässt.
Dies bedeutet, dass Sie bei Eins-zu-Viele-Datensätzen, z. B.
Buchung -> Reisende (Buchung-> Reisende), die Reise-ID in der Anfrage weitergeben müssen.
Schlecht:
#
GET /bookings/{bookingId}/travellers/{travellerId}
Okay:
GET /bookings/travellers/{travellerId}
Ich stelle auch fest, dass /bookings/travellers/
es besser ist, als sich nur gut /travellers
an die Datenhierarchie in Ihrer API zu halten.
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 Abfrageparametern
Bad:
GET /users/{user-id}
GET /users/{user_id}
GET /users/{userid}
Okay:
GET /users/{userId}
POST /ticket/{ticketId}/gold
9.2 Im Hauptteil der Antwort oder der empfangenen Anfrage
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. Verwenden Sie den Inhaltstyp
Schlecht:
GET /tickets.json
GET /tickets.xml
Okay:
GET /tickets
//
ontent-Type: application/json
//
ontent-Type: application/xml
Fazit
Die oben aufgeführten Empfehlungen sind nicht die gesamte Liste der Möglichkeiten, die API zu verbessern. Für weitere Studien empfehle ich, dass Sie die REST-API-Spezifikationen und die Liste der http-Statuscodes analysieren (Sie werden überrascht sein, wie viele es gibt und welche Situationen sie abdecken).
In den Kommentaren schlage ich vor, eine eigene Empfehlung zum Erstellen einer REST-API zu verfassen, die Sie für wichtig halten.