API Review

für OpenAPI, REST, RPC und GraphQL

Technisch ist das Erstellen einer API einfach. Die Herausforderung liegt darin, ein übersichtliches konsistentes Design zu entwerfen, das lange ohne die Kompatibilität zu brechen im Einsatz sein kann.

Gutes Design lohnt sich

  • Abwärtskompatibilität bei gleichzeitiger Erweiterbarkeit
  • Zeitersparnis bei der Client-Entwicklung
  • Weniger Aufwand bei der Versionierung
  • Ersparnis beim Support von Entwicklern

Ein Review beantwortet die Fragen:

  • Wurden Namensmuster verwendet und wurden diese konsequent eingehalten?
  • Wurde gegen die REST Prinzipien verstoßen?
  • Werden die richtigen HTTP Status Codes verwendet?
  • Werden die Parameter an der jeweils passenden Stelle wie z.B. im Path oder Header übergeben?
  • Werden passende Status Codes verwendet?

und zeigt Vorschläge zur:

  • Umbenennung von Resource, JSON Strukturen, ...
  • Umstrukturierung
  • Verbesserung der Modellierung der JSON Strukturen

Wie läuft ein Review ab?

Für die Durchführung des Reviews benötigen wir eine OpenAPI Beschreibung oder andere Dokumentation, zur Not genügt auch der Quellcode oder Beispielnachrichten.

1. Kickoff Meeting (1 – 2h)
  • Vorstellung der API
  • Probleme und Ziele
  • Randbedingungen und Anforderungen
2. Review (4 – 8h)

Wir prüfen die API Beschreibung mit Werkzeugen, der entscheidende Teil ist aber die Sichtung durch den API-Spezialisten, der auch Vorschläge zur Verbesserung ausarbeitet.

3. Ergebnispräsentation (1h)