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.

1. Benutze Nomen, aber keine Verben
2. GET sollte den State nicht verändern
3. Benutze immer Plural-Nomen
4. Benutze Sub-Ressourcen für Beziehungen
5. Benutze Headers für Authorization und Format-Deklarationen
6. Benutze HATEOAS
7. Stelle Filtermöglichkeiten, Sortierung, Seitenaufteilung bereit
8. Versioniere die API: Major Version in der URL, (Datums-basierte) Minor Version in Header
9. Behandle Fehler mit den korrekten HTTP Status Codes
10. Erlaube Überschreiben der HTTP Methode

(Quelle: http://blog.mwaysolutions.com/2014/06/05/10-best-practices-for-better-restful-api/)

1. Nimm dir Freiraum für Aktionen, die nicht ins CRUD Schema passen
2. Benutze immer SSL – ohne Ausnahme!
3. Ausführliche Dokumentation ist extrem wichtig!
4. Erlaube Suche nach Ressourcen
5. Stelle Aliase für gebräuchliche Abfragen bereit
6. Erlaube Limitierung der zurückgegebenen Felder
7. Benutze snake_case anstelle von camelCase
8. Stelle sicher, dass GZip-Kompression unterstützt wird (und Caching auf der Produktionsumgebung angeschaltet ist)
9. Benutze keine Umhüllung für Antworten, aber mache es möglich wo nötig (bspw. für Fehler, siehe obigen Link)
10. Erlaube autom. Laden von verwandten Ressourcen über „embed“ Parameter (erlaube Erweiterung von Beziehungen)
11. Benutze Rate Limiting (z.B. Anzahl Anfragen pro Stunde)
12. 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)

1. Halte URLs so kurz wie möglich, aber auch so klar wie möglich (nicht mehr als 3 Nodes per URL)
2. Benutze Links und Referenz-Objekte anstelle von blanken IDs (=> HATEOAS)
3. Designe Ressourcen-Repräsentationen anstelle von einfacher Ausgabe von Datenbanktabellen
4. Führe Repräsentationen zusammen und zeige nicht ihre blanken IDs an
5. Benutze ISO 8601 Datums- und Zeit-Formatierungen
6. Benutze Content-Type Header um Inhalte von eingehenden Anfragen zu beschreiben (z.B. Content-Type: application/vnd.koehler.webdesign.invoice)
7. Benutze folgende Cache Header:
   1. ETag
   2. Date
   3. Cache-Control
   4. Expires
   5. Pragma
   6. Last-Modified
8. 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)