OpenAPI JSON-Objekte als Abfrageparameter

1. Übersicht

In diesem Tutorial erfahren Sie, wie Sie mit JSON-Objekten als Abfrageparameter mit OpenAPI arbeiten .

2. Abfrageparameter in OpenAPI 2

OpenAPI 2 unterstützt keine Objekte als Abfrageparameter . Es werden nur Grundwerte und Arrays von Grundelementen unterstützt.

Aus diesem Grund möchten wir stattdessen unseren JSON-Parameter als Zeichenfolge definieren.

Um dies in Aktion zu sehen, definieren wir einen Parameter namens params als Zeichenfolge , obwohl wir ihn in unserem Backend als JSON analysieren werden:

swagger: "2.0" ... paths: /tickets: get: tags: - "tickets" summary: "Send an JSON Object as a query param" parameters: - name: "params" in: "path" description: "{\"type\":\"foo\",\"color\":\"green\"}" required: true type: "string" 

Also anstelle von:

GET //localhost:8080/api/tickets?type=foo&color=green

wir machen:

GET //localhost:8080/api/tickets?params={"type":"foo","color":"green"}

3. Parameter in OpenAPI 3 abfragen

OpenAPI 3 bietet Unterstützung für Objekte als Abfrageparameter.

Um einen JSON-Parameter anzugeben, müssen wir unserer Definition einen Inhaltsabschnitt hinzufügen , der den MIME-Typ und das Schema enthält:

openapi: 3.0.1 ... paths: /tickets: get: tags: - tickets summary: Send an JSON Object as a query param parameters: - name: params in: query description: '{"type":"foo","color":"green"}' required: true schema: type: object properties: type: type: "string" color: type: "string" 

Unsere Anfrage kann nun folgendermaßen aussehen:

GET //localhost:8080/api/tickets?params[type]=foo¶ms[color]=green

Und tatsächlich kann es immer noch so aussehen:

GET //localhost:8080/api/tickets?params={"type":"foo","color":"green"}

Die erste Option ermöglicht es uns, Parameterüberprüfungen zu verwenden, die uns vor der Anforderung darüber informieren, ob etwas nicht stimmt.

Mit der zweiten Option tauschen wir dies gegen eine bessere Kontrolle über das Backend sowie OpenAPI 2-Kompatibilität aus.

4. URL-Codierung

Es ist wichtig zu beachten, dass wir bei dieser Entscheidung, Anforderungsparameter als JSON-Objekt zu transportieren, den Parameter per URL codieren möchten, um einen sicheren Transport zu gewährleisten.

Also, um die folgende URL zu senden:

GET /tickets?params={"type":"foo","color":"green"}

Wir würden tatsächlich tun:

GET /tickets?params=%7B%22type%22%3A%22foo%22%2C%22color%22%3A%22green%22%7D

5. Einschränkungen

Beachten Sie auch die Einschränkungen beim Übergeben eines JSON-Objekts als Satz von Abfrageparametern:

  • reduzierte Sicherheit
  • begrenzte Länge der Parameter

Zum Beispiel, je mehr Daten wir in einem Abfrage - Parametern setzen , desto mehr erscheint in Server - Logs und desto höher ist das Potential für sensible Daten Exposition.

Ein einzelner Abfrageparameter darf nicht länger als 2048 Zeichen sein. Natürlich können wir uns alle Szenarien vorstellen, in denen unsere JSON-Objekte größer sind. In der Praxis beschränkt uns eine URL-Codierung unserer JSON-Zeichenfolge auf etwa 1000 Zeichen für unsere Nutzlast.

Eine Problemumgehung besteht darin, größere JSON-Objekte im Hauptteil zu senden. Auf diese Weise beheben wir sowohl das Sicherheitsproblem als auch die JSON-Längenbeschränkung.

Tatsächlich unterstützen GET oder POST dies beide. Ein Grund, einen Body über GET zu senden, besteht darin, die RESTful-Semantik unserer API beizubehalten.

Natürlich ist es etwas ungewöhnlich und wird nicht allgemein unterstützt. Beispielsweise erlauben einige JavaScript-HTTP-Bibliotheken nicht, dass GET-Anforderungen einen Anforderungshauptteil haben.

Kurz gesagt, diese Wahl ist ein Kompromiss zwischen Semantik und universeller Kompatibilität.

6. Fazit

Zusammenfassend haben wir in diesem Artikel gelernt, wie JSON-Objekte mit OpenAPI als Abfrageparameter angegeben werden. Dann haben wir einige der Auswirkungen auf das Backend beobachtet.

Die vollständigen OpenAPI-Definitionen für diese Beispiele sind auf GitHub verfügbar.