In moderner Web-Entwicklung dreht sich viel um APIs, meistens RESTful APIs. Wenn man Applikationen auf mehrere Server aufteilen will oder Microservices implementieren will, müssen diese miteinander kommunizieren – meistens über eine RESTful API. Darum habe ich aus verschiedenen Quellen im Web hier die „Best Practices“ für das Architektur-Design einer RESTful API zusammengetragen.
- Benutze Nomen, aber keine Verben
- GET sollte den State nicht verändern
- Benutze immer Plural-Nomen
- Benutze Sub-Ressourcen für Beziehungen
- Benutze Headers für Authorization und Format-Deklarationen
- Benutze HATEOAS
- Stelle Filtermöglichkeiten, Sortierung, Seitenaufteilung bereit
- Versioniere die API: Major Version in der URL, (Datums-basierte) Minor Version in Header
- Behandle Fehler mit den korrekten HTTP Status Codes
- Erlaube Überschreiben der HTTP Methode
(Quelle: http://blog.mwaysolutions.com/2014/06/05/10-best-practices-for-better-restful-api/)
- Nimm dir Freiraum für Aktionen, die nicht ins CRUD Schema passen
- Benutze immer SSL – ohne Ausnahme!
- Ausführliche Dokumentation ist extrem wichtig!
- Erlaube Suche nach Ressourcen
- Stelle Aliase für gebräuchliche Abfragen bereit
- Erlaube Limitierung der zurückgegebenen Felder
- Benutze snake_case anstelle von camelCase
- Stelle sicher, dass GZip-Kompression unterstützt wird (und Caching auf der Produktionsumgebung angeschaltet ist)
- Benutze keine Umhüllung für Antworten, aber mache es möglich wo nötig (bspw. für Fehler, siehe obigen Link)
- Erlaube autom. Laden von verwandten Ressourcen über „embed“ Parameter (erlaube Erweiterung von Beziehungen)
- Benutze Rate Limiting (z.B. Anzahl Anfragen pro Stunde)
- Authentifizierung sollte statuslos sein. ?access_token= URL-Parameter sollte nur in Verbindung mit JSONP erlaubt werden
(Quelle: http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api#restful)
- Halte URLs so kurz wie möglich, aber auch so klar wie möglich (nicht mehr als 3 Nodes per URL)
- Benutze Links und Referenz-Objekte anstelle von blanken IDs (=> HATEOAS)
- Designe Ressourcen-Repräsentationen anstelle von einfacher Ausgabe von Datenbanktabellen
- Führe Repräsentationen zusammen und zeige nicht ihre blanken IDs an
- Benutze ISO 8601 Datums- und Zeit-Formatierungen
- Benutze Content-Type Header um Inhalte von eingehenden Anfragen zu beschreiben (z.B. Content-Type: application/vnd.koehler.webdesign.invoice)
- Benutze folgende Cache Header:
- ETag
- Date
- Cache-Control
- Expires
- Pragma
- Last-Modified
- Stelle idempotente (englisch) Operationen sicher.
(Quelle: https://github.com/RestCheatSheet/api-cheat-sheet#api-design-cheat-sheet)
Siehe auch: Web API Standards by The White House; Washington, D.C. (englisch)
GD Star Rating
loading...
Gefällt mir:
Gefällt mir Lade …
Ähnliche Beiträge
Kommentar verfassen