Einführung in den Abschnitt „API-Pfade“

API-Entwicklung

Ossi Galkin avatarGeschrieben vonOssi Galkin Vor über einer Woche aktualisiertTable of contents

Abschnitt „API-Pfade“

Der zweite Hauptteil der API-Definition ist das Paths-Objekt. Das Paths-Objekt definiert alle relativen Pfade zu allen Endpunkten und ihren Operationen, die diese API bietet.

Dies ist ein Beispiel für ein Paths-Objekt, das eine Pfaddefinition und eine GET-Operation für den Pfad enthält:

Pfade: /now: get: Parameter: - Name: Format in: Abfragebeschreibung: Format für zurückgegebenes Datum und/oder Uhrzeit erforderlich: true Schema: Typ: Zeichenfolge Antworten: „200“: Beschreibung: ok Inhalt: Anwendung/Text: Schema: Typ: Zeichenfolge

Objekt / Artikel

Beschreibung

Pfade:

Das Pfadobjekt enthält die relativen Pfade zu den einzelnen Endpunkten und ihren Vorgängen. Der Pfad wird an die URL vom Serverobjekt (beschrieben im Abschnitt API-Header) angehängt, um die vollständige URL.ull-URL zu erstellen.

/Jetzt:

Dies ist ein Pfadelementobjekt, das die auf einem einzelnen Pfad verfügbaren Operationen beschreibt. Wenn Sie Pfadparameter verwenden möchten, müssen Sie diese hier definieren.

Bitte beachten Sie diePfadelementobjektDokumentation.

erhalten:

Dies ist das Operationsobjekt, das eine einzelne API-Operation auf einem Pfad beschreibt. Unter einem Pfadelementobjekt können sich ein oder mehrere Operationsobjekte befinden.

Bitte beachten Sie dieReferenzdokumentation für OperationsobjektDokumentation.

Parameter: - Name: Format in: Abfrage Beschreibung: Format für zurückgegebenes Datum und/oder Uhrzeit erforderlich: true Schema: Typ: Zeichenfolge

Verwenden Sie den Parameterabschnitt, wenn Sie Parameter verwenden möchten. Sie können einen oder mehrere Parameter für den API-Vorgang definieren. Jedes Parameterobjekt enthält die folgenden Felder:

  • Name: Name des Parameters. Dies ist ein Pflichtfeld.

  • in: Der Speicherort des Parameters. Mögliche Werte sind „Query“, „Header“, „Path“ oder „Cookie“. Dies ist ein Pflichtfeld.

  • Beschreibung: Eine kurze Textbeschreibung des Parameters.

  • erforderlich: Legt fest, ob dieser Parameter obligatorisch ist. Wenn der Parameterspeicherort „Pfad“ ist, ist diese Eigenschaft ERFORDERLICH und ihr Wert MUSS „true“ sein. Andernfalls KANN die Eigenschaft eingeschlossen werden und ihr Standardwert ist „false“.

  • Schema: Das Schema, das den für den Parameter verwendeten Typ definiert.

Bitte beachten Sie dieParameterobjektdokumentation.

Antworten: '200': Beschreibung: ok Inhalt: Anwendung/Text: Schema: Typ: Zeichenfolge

Das Antwortobjekt dokumentiert und definiert die möglichen HTTP-Antwortcodes des API-Vorgangs. Es ist nicht erforderlich, alle möglichen Antwortcodes abzudecken, es empfiehlt sich jedoch, alle erfolgreichen Antworten und alle bekannten Fehler abzudecken.

Bitte beachten Sie dieAntworten Objektdokumentationfür Details und weitere Beispiele.

Beim Definieren von REST-APIs mit OpenAPI-Spezifikation wird empfohlen, allgemeine Richtlinien für REST-Statuscodes zu befolgen. Weitere Informationen finden Sie beispielsweise unter „Der vollständige Leitfaden zu Statuscodes für aussagekräftige REST-APIs.

Der nächste Artikel istEinführung in die API-Authentifizierung


Verwandte ArtikelErstellen einer Frends-APIEinführung in API TriggerEinführung in den Header-Abschnitt der API-DefinitionEinführung in die API-TriggereinstellungenEinführung in die Definition der Verwendung von API-Schlüsseln in der OpenAPI-Spezifikation