REST Api Guidelines und OpenAPI


Da heutzutage immer mehr Dienste direkt per HTTP-Aufrufe ansprechbar sind, haben alle großen Hersteller von Webdiensten mittlerweile API-Guidelines zur Erstellung dieser Dienste. Dies kann manchmal hilfreich sein, wenn es um kryptische Fehlermeldungen in Log-Dateien geht.

Hier der Verweis auf die API-Guidelines von Microsoft: https://github.com/Microsoft/api-guidelines/blob/vNext/Guidelines.md und von Google: https://cloud.google.com/apis/design/. Guidelines von Amazon konnte ich noch keine ausfindig machen, daher nur ein Link auf die aktuelle API: https://docs.aws.amazon.com/apigateway/api-reference/. Es gibt auch bereits Seiten, welche sich den Guidelines annehmen und diese wieder auf bestimmte Kriterien untersuchen zum besseren Vergleichen: http://apistylebook.com/design/guidelines/.

Ein Punkt der beim Datenaustausch zwischen verschiedenen APIs für Verwirrung sorgen könnte, sind Datumsfelder. Bei Google ist die Rede von RFC3339 (http://tools.ietf.org/html/rfc3339), bei Microsoft von ISO8601. Beide sind sich ähnlich allerdings unterscheiden sie sich in ein paar Kleinigkeiten, die im Zweifel wie immer alles durcheinander bringen können: https://stackoverflow.com/questions/522251/whats-the-difference-between-iso-8601-and-rfc-3339-date-formats.

Wo findet man nun diese Guidelines angewendet? Z. B. hier: https://cloud.google.com/apis/docs/overview oder beim Microsoft Graph: https://developer.microsoft.com/de-de/graph/docs/concepts/overview.

Wenn wir schon dabei sind, muss ich noch OpenAPI nennen, welches in Zukunft auch größere Bedeutung bekommen dürfte: https://www.openapis.org/specification/repo bzw. https://swagger.io/specification/. Als alter Powersheller sollte ich dabei noch gleich auf PSSwagger verweisen: https://github.com/PowerShell/PSSwagger. Mit PSSwagger lassen sich aus bestehenden OpenAPI-Definitionen automatisch Cmdlets erstellen. Wer es allgemeiner benötigt kann auch AutoRest von MS verwenden: https://github.com/Azure/autorest.

Wer wendet nun OpenAPIs bereits an? Na z. B. Google: https://cloud.google.com/endpoints/docs/openapi/. Auch Microsoft ist bei seinen Azure-Bemühungen mit dabei und hat sich klar zu OpenAPI bekannt: https://blogs.msdn.microsoft.com/apimanagement/2016/10/24/swaggers-success-gives-birth-to-openapi/.

Mit der aktuellen OpenAPI Spezifikation 3.0 dürfte nun der API-Zug endgültig den Bahnhof verlassen und schnell Fahrt aufnehmen…

Wenn ich irgendetwas zum Thema vergessen habe sollte, findet man es sicher hier. https://design.apievangelist.com/.

Advertisements

Eine Antwort to “REST Api Guidelines und OpenAPI”

  1. Quirel Says:

    Noch ein Hinweis zu ISO8601 Datum und .Net!

    https://blogs.msdn.microsoft.com/shawnste/2006/01/24/iso-8601-week-of-year-format-in-microsoft-net/

Kommentar verfassen

Trage deine Daten unten ein oder klicke ein Icon um dich einzuloggen:

WordPress.com-Logo

Du kommentierst mit Deinem WordPress.com-Konto. Abmelden / Ändern )

Twitter-Bild

Du kommentierst mit Deinem Twitter-Konto. Abmelden / Ändern )

Facebook-Foto

Du kommentierst mit Deinem Facebook-Konto. Abmelden / Ändern )

Google+ Foto

Du kommentierst mit Deinem Google+-Konto. Abmelden / Ändern )

Verbinde mit %s


%d Bloggern gefällt das: