11. Gib die bei POST erstellte Ressource zurück
Es ist eine gute Idee, die erstellte Ressource zurückzugeben, nachdem sie mit einer POST-Anfrage erstellt wurde. Das ist vor allem deshalb wichtig, weil die zurückgegebene, erstellte Ressource den aktuellen Zustand der zugrundeliegenden Datenquelle widerspiegelt und vielleicht aktuellere Informationen enthält (z. B. eine generierte ID).
// Request: POST /users
{
"email": "jdoe@averagecompany.com",
"name": "John Doe"
}
// Response
{
"id": "T9hoBuuTL4",
"email": "jdoe@averagecompany.com",
"name": "John Doe"
}
12. Bevorzuge PATCH gegenüber PUT
Wie bereits erwähnt, sollten PATCH-Anfragen partielle Aktualisierungen auf eine Ressource anwenden, während PUT eine bestehende Ressource vollständig ersetzt. Es ist normalerweise eine gute Idee, Aktualisierungen um PATCH-Anfragen herum zu entwerfen, denn:
Bei der Verwendung von PUT, um nur eine Teilmenge von Feldern einer Ressource zu aktualisieren, muss immer noch die gesamte Ressource übertragen werden, was die Netzwerkintensität und Fehleranfälligkeit erhöht. Es ist auch ziemlich gefährlich, jedes beliebige Feld ohne jegliche Einschränkungen zu aktualisieren. Es gibt in der Praxis kaum Anwendungsfälle, in denen eine vollständige Aktualisierung einer Ressource sinnvoll wäre. Hat man z.B. eine Auftragsressource, die eine ID und einen Status hat, dann wäre sehr gefährlich, den Anwendern zu erlauben, den Status einer Bestellung zu aktualisieren. Eine Zustandsänderung würde viel eher durch einen anderen Endpunkt ausgelöst werden (z. B. /orders/{id}/fulfill)
13. Sei so spezifisch wie möglich
Wie im vorigen Abschnitt beschrieben, ist es im Allgemeinen eine gute Idee, bei der Entwicklung von Endpunkten, der Benennung von Feldern und der Entscheidung, welche Anfragen und Antworten akzeptiert werden sollen, so spezifisch wie möglich zu sein. Wenn eine PATCH-Anfrage nur zwei Felder (Name und Beschreibung) akzeptiert, besteht keine Gefahr, dass sie falsch verwendet wird und Daten beschädigt werden.
14. Verwende Paginierung
Paginiere alle Anfragen, die eine Sammlung von Ressourcen zurückgeben und dieselbe Antwortstruktur verwenden. Verwende page_number und page_size (oder ähnliches), um zu steuern, welcher Teil abgerufen werden soll.
// Request => GET /users?page_number=1&page_size=15
// Response <= 200 OK
{
"page_number": 1,
"page_size": 15,
"count": 378,
"data": [
// resources
],
"total_pages": 26,
"has_previous_page": true,
"has_next_page": true
}
15. Erlaube die Erweiterung von Ressourcen
Erlaube Anwendern, zusammenhängende Daten mit einem Abfrageparameter namens expand (oder ähnlich) zu laden. Dies ist besonders nützlich, um Roundtrips zu vermeiden und alle Daten, die für eine bestimmte Aktion erforderlich sind, in einem Durchgang zu laden.
// Request => GET /users/T9hoBuuTL4?expand=orders&expand=orders.items
// Response <= 200 OK
{
"id": "T9hoBuuTL4",
"email": "jdoe@averagecompany.com",
"name": "John Doe",
"orders": [
{
"id": "Hy3SSXU1PF",
"items": [
{
"name": "API course"
},
{
"name": "iPhone 13"
}
]
},
{
"id": "bx1zKmJLI6",
"items": [
{
"name": "SaaS subscription"
}
]
}
]
}