Geschrieben vonOssi Galkin Vor über einer Woche aktualisiertTable of contents
Frends ist eine Plattform für die schnelle Entwicklung von Integrationen, die neben vielen anderen Funktionen eine schnelle Web-API-Entwicklung unterstützt. Es gibt jedoch viele Möglichkeiten, dasselbe zu erreichen, sowie Änderungen an der genauen Implementierung, die sich aus Versionsaktualisierungen ergeben. Der Zweck dieses Blogs besteht darin, Sie über die besten Ansätze zu beraten und Sie mit der Erfahrung eines erfahrenen Frends-API-Entwicklers durch verschiedene Versionen zu führen. Natürlich gibt es bei der Entwicklung von APIs viele Dinge zu beachten, aber dieser erste Teil führt Sie durch die folgenden Themen:
Soll ich Swagger oder OpenAPI verwenden?
Wie sollte ich im Hinblick auf zukünftige Erweiterungen meine API und ihre Operationen benennen?
Wie schütze ich meine API?
Soll ich Abfrage- oder Pfadparameter definieren?
Swagger oder OpenAPI?
Ursprünglich begann die Frends API-Entwicklung mit Unterstützung für Swagger/OpenAPI 2.0, wobei die volle Unterstützung für die OpenAPI 3.0-Spezifikation in Version 5.3 veröffentlicht wurde. Die Wahl zwischen Swagger/OpenAPI 2.0 und der OpenAPI 3.0-Spezifikation hängt nur von einer Sache ab:
Wenn Sie mit einer Frends-Version vor 5.3 arbeiten, ist OpenAPI 2.0 die einzige Wahl;
Ab 5.3 wird empfohlen, die neueste Version der Spezifikation zu verwenden.
Achtung!Wenn Ihre aktuelle Frends-Umgebung der 5.2.x-Serie entspricht und Sie planen, auf Version 5.3 oder höher zu aktualisieren, wird empfohlen, die OpenAPI 2.0-Spezifikation auf Version 3.0 zu konvertieren. Mit der Versionsänderung wurde die Validierung der OpenAPI-Spezifikation strenger, und infolgedessen funktionieren Funktionen oder das Sicherheitsschema für API-Schlüssel möglicherweise nicht mehr wie zuvor (Bitte beachten Sie die Versionshinweise).
Das Referenzhandbuch zu OpenAPI 2.0 finden Sie unterHier.
Das Referenzhandbuch zu OpenAPI 3.0 finden Sie unterHier.
Benennung der API und der Operationen
Beim Schreiben einer API-Spezifikation für z. B. eine Zoohandlung könnte der Entwickler versucht sein, den Namen der API nach dem Versionskennzeichen zu schreiben, sodass die URL wie folgt aussieht: contoso.com/api/v1/petstore. Dies könnte später Zeit sparen, da Sie den verschiedenen Vorgängen keine Versionsnummern hinzufügen müssen.
Was aber würde passieren, wenn eine Operation, z. B. `/inventory`, aktualisiert werden müsste, die alte Version aber gleichzeitig aus Gründen der Abwärtskompatibilität betriebsbereit bleiben soll? Sie müssten eine völlig neue API-Spezifikation schreiben und dann zwei verschiedene `/inventory`-Methoden in zwei verschiedenen Spezifikationen pflegen.
Der empfohlene Ansatz für die API- und Vorgangsbenennung ist wie folgt:
1. Setzen Sie den Namen der API nach dem Schlüsselwort „API“ (das Schlüsselwort „API“ muss gemäß den Frends-Anforderungen das erste Namenselement sein):
- Swagger/OpenAPI 2.0: Schreiben Sie das Element „basePath“ wie folgt:
```
"basePath": "/api/petstore", ...
```
- OpenAPI 3.0: Schreiben Sie das Element „servers[].url“ wie folgt:
```
"Server": [
{ "url": "https://localhost/api/petstore" }
], ...
```
2. Fügen Sie die Operationen dem Objekt „Pfade“ hinzu, mit der Versionsnummer („v1“) vor dem Operationsnamen:
```
"Pfade": {
"/v1/Inventar": {
...
},
...
}
```
– Im Allgemeinen werden lange und komplizierte Pfadnamen nicht unterstützt; „/inventory“ oder „/inventory/{storeid}“ sind immer noch einfach genug zu verstehen.
- Einen Leitfaden zur Ressourcenbenennung finden SieHier
3. Wenn Sie der API jemals eine Operation mit demselben Namen, aber anderem Inhalt oder anderer Funktionalität hinzufügen müssen, können Sie dies mit der nächsten verfügbaren Versionsnummer angeben, z. B. „v2“.
Beschreiben der Authentifizierung
Frends bietet mehrere Authentifizierungsmethoden für API-Operationen und dieDokumentation zu API-Triggerndeckt alle Fälle ab.
Beim Schreiben einer API-Spezifikation muss berücksichtigt werden, wie diese verschiedenen Sicherheitsschemata angewendet werden:
Soll die gesamte API mit allen ihren Operationen durch Authentifizierung geschützt werden, oder
sollten nur einige Operationen (meist Schreiboperationen) der API eine Authentifizierung erfordern.
Im ersten Fall sollte die Anwendung von Sicherheit auf der Stammebene der API-Spezifikation ausreichen, während im zweiten Fall das Sicherheitsschema zusammen mit jeder Operation deklariert werden muss, die es erfordert. Die Online-Dokumentation von OpenAPI beschreibt, wie jeder Fall durchgeführt wird:
- für OpenAPI 2.0Hier, Und
- für OpenAPI 3.0Hier.
Beschreiben von Anforderungsparametern
Es mag verlockend sein, eine Anfrage nur als GET-Anfrage zu beschreiben, die alle erforderlichen Informationen zur Verarbeitung als Abfrage- und/oder Pfadparameter erhält. Für einige Anwendungsfälle ist dies jedoch absolut nicht zu empfehlen. Hier ist eine kurze Übersicht, was diese verschiedenen Parameter sind und wann sie verwendet werden können oder sollten.
Pfadparameter
Möglicherweise ist Ihnen bereits früher ein Pfadparameter aufgefallen, z. B. `/inventory/{storeid}`. Wenn der Parameter ein kodierter Bezeichner ohne Sonderzeichen ist, ist es logisch, diesen zu verwenden. Andernfalls sollten Sie einen Abfrageparameter oder, im Fall von sensiblen Daten wie Sozialversicherungsnummern und Kreditkartennummern, einen Body-Parameter verwenden. Alle in der URI übergebenen Informationen werden ungeschützt weitergeleitet und können von mehreren Entitäten protokolliert werden. Weitere Einzelheiten finden Sie unterdie OWASP Foundation.
Ein kurzes Beispiel zum Definieren eines Pfadparameters, Fallpfad: `/inventory/{storeid}`:
Mit OpenAPI 2.0:
```
"Parameter": [
{
„Name“: „gespeichert“,
"in": "Pfad",
"description": "Shop-Identifikationscode",
"erforderlich": wahr,
"Typ": "Zeichenfolge"
},
...
]
```
Mit OpenAPI 3.0:
```
"Parameter": [
{
"Name": "Berichtsdatum",
"in": "Abfrage",
"description": "Der Lagerbestand für welchen Tag soll gemeldet werden",
"erforderlich": falsch,
"Schema": {
"Typ": "Zeichenfolge",
"Format": "Datum"
}
},
...
]
```
Dieser Parameter kann dann wie folgt verwendet werden: `/inventory/{storeid}?reportdate=2021-05-15`
Körperparameter
Für komplexe Datenstrukturen, lange Dokumente und sensible (persönliche) Informationen ist ein Body-Parameter die richtige Wahl. Body-Parameter können mit `POST`-, `PUT`- und `PATCH`-Anfragen übergeben werden.
Ein kurzes Beispiel zum Definieren eines Body-Parameters, Fallpfad: `/inventory/{storeid}`:
Mit OpenAPI 2.0:
```
"Parameter": [
{
"Name": "Inventar",
"in": "Körper",
"description": "Inventar des angegebenen Geschäfts",
"erforderlich": wahr,
"Schema": {
"Typ": "Array",
"Artikel": {
"$ref": "#/definitionen/Inventar"
}
}
},
...
]
```
Mit OpenAPI 3.0:
```
"Anfragetext": {
"description": "Inventar des angegebenen Geschäfts",
"erforderlich": wahr,
"Inhalt": {
"Anwendung/json": {
"Schema": {
"Typ": "Array",
"Artikel": {
"$ref": "#/Komponenten/Schemas/Inventar"
}
}
}
}
},
...
```
Überprüfen von Parametern
Obwohl ein Benutzer in der API-Spezifikation komplizierte Details für das Format der Parameter definieren kann, führt Frends tatsächlich keine Validierung für diese durch. Natürlich wird die Schnittstelle sich beschweren, wenn ein Benutzer die Implementierung über die Swagger-Benutzeroberfläche von Frends testet, wenn in der Anfrage ein erforderlicher Parameter fehlt. Aber das ist auch schon alles.
Das Gute ist, dass Sie die Validierung in der Frends-Implementierung der Operation mit einer dieser beiden benutzerdefinierten Aufgaben implementieren können, wenn Sie das Datenobjekt in der Spezifikation im JSON-Format beschrieben haben oder Zugriff auf eine XSD-Schemadatei haben:
- Frends.Json.Validate
- Frends.Xml.Validate
Die empfohlene Methode zum Validieren von Abfrageparametern ist die Verwendung von Codeformen oder -anweisungen.
Abschluss
Wenn Sie bis hierhin gelesen haben, stellen Sie sich möglicherweise folgende Fragen:
Wie sollte ich die API-Operation *wirklich* definieren und welche HTTP-Anforderungsmethode sollte diese Operation verwenden? (Dies wurde bereits in Teil 4 kurz besprochen, aber ich bin immer noch verwirrt.)
Wie soll ich Antwortnachrichten definieren?
Ich brauche SOAP! Was ist mit XML?
Keine Panik! Im zweiten Teil dieser Blogserie werden wir genauer auf diese Fragen eingehen.
Bleiben Sie dran!
Verwandte ArtikelErstellen einer Frends-APIFreundesterminologieEinführung in die OpenAPI-SpezifikationEinführung in OpenAPI 2.0 und OpenAPI 3.0Einführung in die API-Spezifikation So verwenden Sie den Swagger Editor