Strukturierung der Online-Dokumentation für eine REST-API

85

Ich erstelle meine erste Rest-API, die Daten in JSON- und XML-Formate serialisiert. Ich möchte API-Clients eine Indexseite zur Verfügung stellen, auf der sie implementierte Endpunkte auswählen können.

Welche Informationen muss ich einschließen, um meine API am nützlichsten zu machen, und wie soll ich sie organisieren?

api rest indexing aumanets
quelle

Antworten:

6

Das ist eine sehr komplexe Frage für eine einfache Antwort.

Möglicherweise möchten Sie einen Blick auf vorhandene API-Frameworks wie Swagger Specification ( OpenAPI ) und Dienste wie apiary.io und apiblueprint.org werfen .

Hier ist auch ein Beispiel für dieselbe REST-API, die auf drei verschiedene Arten beschrieben, organisiert und sogar gestaltet wurde. Es kann ein guter Anfang für Sie sein, aus bestehenden gemeinsamen Methoden zu lernen.

Ich denke, auf der obersten Ebene erfordern hochwertige REST-API-Dokumente mindestens Folgendes:

  • eine Liste aller Ihrer API-Endpunkte (Basis- / relative URLs)
  • entsprechender HTTP-Methodentyp GET / POST / ... für jeden Endpunkt
  • Anfrage / Antwort MIME-Typ (wie man Parameter codiert und Antworten analysiert)
  • eine Beispielanforderung / -antwort, einschließlich HTTP-Headern
  • Typ und Format, die für alle Parameter angegeben wurden, einschließlich der in URL, Body und Headern
  • eine kurze Textbeschreibung und wichtige Hinweise
  • Ein kurzer Code-Ausschnitt, der die Verwendung des Endpunkts in gängigen Web-Programmiersprachen zeigt

Es gibt auch viele JSON / XML-basierte Dokument-Frameworks, die Ihre API-Definition oder Ihr API-Schema analysieren und einen praktischen Satz von Dokumenten für Sie generieren können. Die Wahl eines Systems zur Dokumentenerstellung hängt jedoch von Ihrem Projekt, Ihrer Sprache, Ihrer Entwicklungsumgebung und vielen anderen Faktoren ab.

Igor Kroitor
quelle