OpenAPI JSON-objekter som forespørgselsparametre

1. Oversigt

I denne vejledning lærer vi at arbejde med JSON-objekter som forespørgselsparametre ved hjælp af OpenAPI.

2. Forespørgselsparametre i OpenAPI 2

OpenAPI 2 understøtter ikke objekter som forespørgselsparametre; kun primitive værdier og arrays af primitiver understøttes.

På grund af det vil vi i stedet definere vores JSON-parameter som en snor.

For at se dette i aktion, lad os definere en parameter kaldet params som en snor, selvom vi analyserer det som JSON i vores backend:

swagger: "2.0" ... stier: / tickets: get: tags: - "tickets" resume: "Send et JSON-objekt som en forespørgsel param" parametre: - navn: "params" i: "sti" beskrivelse: "{ \ "type \": \ "foo \", \ "color \": \ "grøn \"} "kræves: sand type:" streng "

Således i stedet for:

FÅ // localhost: 8080 / api / tickets? Type = foo & color = green

vi gør:

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

3. Forespørgselsparametre i OpenAPI 3

OpenAPI 3 introducerer understøttelse af objekter som forespørgselsparametre.

For at specificere en JSON-parameter skal vi tilføje en indhold sektion til vores definition, der inkluderer MIME-typen og skemaet:

openapi: 3.0.1 ... stier: / tickets: get: tags: - billedsammendrag: Send et JSON-objekt som en forespørgsel parametre: - navn: params i: forespørgselsbeskrivelse: '{"type": "foo", "farve": "grøn"} 'kræves: sandt skema: type: objektegenskaber: type: type: "streng" farve: type: "streng"

Vores anmodning kan nu se ud:

FÅ // localhost: 8080 / api / tickets? Params [type] = foo¶ms [color] = green

Og faktisk kan det stadig se ud:

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

Den første mulighed giver os mulighed for at bruge parametervalideringer, som giver os besked, hvis der er noget galt, før anmodningen er fremsat.

Med den anden mulighed handler vi for større kontrol på backend samt OpenAPI 2-kompatibilitet.

4. URL-kodning

Det er vigtigt at bemærke, at når vi træffer denne beslutning om at transportere anmodningsparametre som et JSON-objekt, vil vi URL-kode parameteren for at sikre sikker transport.

Så for at sende følgende URL:

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

Vi ville faktisk gøre:

FÅ / billetter? Params =% 7B% 22type% 22% 3A% 22foo% 22% 2C% 22farve% 22% 3A% 22grøn% 22% 7D

5. Begrænsninger

Lad os også huske begrænsningerne ved at sende et JSON-objekt som et sæt forespørgselsparametre:

nedsat sikkerhed
begrænset længde af parametrene

For eksempel, jo flere data placerer vi i en forespørgselsparameter, jo mere vises i serverlogfiler og jo højere er potentialet for følsom dataeksponering.

Desuden kan en enkelt forespørgselsparameter ikke være længere end 2048 tegn. Bestemt kan vi alle forestille os scenarier, hvor vores JSON-objekter er større end det. Praktisk set en URL-kodning af vores JSON-streng vil faktisk begrænse os til ca. 1000 tegn for vores nyttelast.

En løsning er at sende større JSON-objekter i kroppen. På denne måde løser vi både sikkerhedsproblemet og JSON-længdebegrænsningen.

Rent faktisk, GET eller POST støtter begge dette. En grund til at sende et organ over GET er at opretholde den RESTful semantik i vores API.

Selvfølgelig er det lidt usædvanligt og understøttes ikke universelt. For eksempel tillader nogle JavaScript HTTP-biblioteker ikke, at GET-anmodninger har et anmodningsorgan.

Kort sagt er dette valg en afvejning mellem semantik og universel kompatibilitet.

6. Konklusion

For at opsummere lærte vi i denne artikel, hvordan man specificerer JSON-objekter som forespørgselsparametre ved hjælp af OpenAPI. Derefter observerede vi nogle af konsekvenserne for backend.

De komplette OpenAPI-definitioner til disse eksempler findes på GitHub.

streamalism.org