streamalism.org

1. Overzicht

In deze zelfstudie leren we hoe u kunt werken met JSON-objecten als queryparameters met OpenAPI.

2. Queryparameters in OpenAPI 2

OpenAPI 2 ondersteunt geen objecten als queryparameters; alleen primitieve waarden en arrays van primitieven worden ondersteund.

Daarom willen we in plaats daarvan onze JSON-parameter definiëren als een draad.

Om dit in actie te zien, definiëren we een parameter met de naam params als een draad, ook al parsen we het als JSON in onze backend:

swagger: "2.0" ... paden: / tickets: get: tags: - "tickets" samenvatting: "Stuur een JSON-object als een queryparameter" parameters: - naam: "params" in: "pad" beschrijving: "{ \ "type \": \ "foo \", \ "color \": \ "green \"} "vereist: true type:" string " 

Dus in plaats van:

GET // localhost: 8080 / api / tickets? Type = foo & color = groen

we zullen doen:

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

3. Queryparams in OpenAPI 3

OpenAPI 3 introduceert ondersteuning voor objecten als queryparameters.

Om een ​​JSON-parameter op te geven, moeten we een inhoud sectie volgens onze definitie die het MIME-type en schema bevat:

openapi: 3.0.1 ... paden: / tickets: get: tags: - samenvatting tickets: Stuur een JSON-object als een queryparameter parameters: - naam: params in: querybeschrijving: '{"type": "foo", "color": "green"} 'vereist: waar schema: type: objecteigenschappen: type: type: "string" color: type: "string" 

Ons verzoek kan er nu als volgt uitzien:

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

En eigenlijk kan het er nog steeds uitzien als:

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

Met de eerste optie kunnen we parametervalidaties gebruiken, die ons laten weten of er iets mis is voordat het verzoek wordt gedaan.

Met de tweede optie ruilen we dat in voor meer controle over de backend en voor OpenAPI 2-compatibiliteit.

4. URL-codering

Het is belangrijk op te merken dat bij het nemen van deze beslissing om verzoekparameters als een JSON-object te transporteren, we de parameter URL-coderen om veilig transport te garanderen.

Dus om de volgende URL te verzenden:

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

We zouden eigenlijk doen:

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

5. Beperkingen

Laten we ook rekening houden met de beperkingen van het doorgeven van een JSON-object als een set queryparameters:

• verminderde beveiliging
• beperkte lengte van de parameters

Bijvoorbeeld, hoe meer gegevens we in een queryparameter plaatsen, hoe meer er wordt weergegeven in serverlogboeken en hoe groter de kans op blootstelling van gevoelige gegevens.

Bovendien mag een enkele queryparameter niet langer zijn dan 2048 tekens. We kunnen ons natuurlijk allemaal scenario's voorstellen waarin onze JSON-objecten groter zijn dan dat. Praktisch gesproken een URL-codering van onze JSON-string zal ons feitelijk beperken tot ongeveer 1000 karakters voor onze payload.

Een oplossing is om grotere JSON-objecten in de hoofdtekst te verzenden. Op deze manier lossen we zowel het beveiligingsprobleem als de JSON-lengtebeperking op.

Werkelijk, GET of POST ondersteunen dit beide. Een reden om een ​​body over GET te sturen, is om de RESTful-semantiek van onze API te behouden.

Het is natuurlijk een beetje ongebruikelijk en niet universeel ondersteund. Sommige JavaScript-HTTP-bibliotheken staan ​​bijvoorbeeld niet toe dat GET-verzoeken een hoofdtekst van een verzoek hebben.

Kortom, deze keuze is een afweging tussen semantiek en universele compatibiliteit.

6. Conclusie

Samenvattend hebben we in dit artikel geleerd hoe we JSON-objecten kunnen specificeren als queryparameters met OpenAPI. Vervolgens hebben we enkele van de implicaties op de backend bekeken.

De volledige OpenAPI-definities voor deze voorbeelden zijn beschikbaar op GitHub.