streamalism.org

1. Oversikt

I denne opplæringen lærer vi hvordan vi kan jobbe med JSON-objekter som søkeparametere ved hjelp av OpenAPI.

2. Spørsmålsparametere i OpenAPI 2

OpenAPI 2 støtter ikke objekter som søkeparametere; bare primitive verdier og matriser av primitiver støttes.

På grunn av det vil vi i stedet definere JSON-parameteren vår som en streng.

For å se dette i aksjon, la oss definere en parameter som heter params som en streng, selv om vi analyserer det som JSON i vår backend:

swagger: "2.0" ... stier: / tickets: get: tags: - "tickets" sammendrag: "Send et JSON-objekt som en spørringsparameter" parametere: - navn: "params" i: "path" beskrivelse: "{ \ "type \": \ "foo \", \ "color \": \ "green \"} "required: true type:" string " 

Dermed, i stedet for:

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

vi skal gjøre:

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

3. Spørringsparametere i OpenAPI 3

OpenAPI 3 introduserer støtte for objekter som søkeparametere.

For å spesifisere en JSON-parameter, må vi legge til en innhold seksjon til vår definisjon som inkluderer MIME-typen og skjemaet:

openapi: 3.0.1 ... stier: / tickets: get: tags: - billedsammendrag: Send et JSON-objekt som et søkeparametere: - navn: params i: spørringsbeskrivelse: '{"type": "foo", "color": "green"} 'required: true schema: type: object properties: type: type: "string" color: type: "string" 

Forespørselen vår kan nå se ut som:

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

Og faktisk kan det fremdeles se ut:

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

Det første alternativet lar oss bruke parametervalideringer, som vil gi oss beskjed hvis noe er galt før forespørselen blir gjort.

Med det andre alternativet bytter vi det for større kontroll på backend samt OpenAPI 2-kompatibilitet.

4. URL-koding

Det er viktig å merke seg at når vi tar denne beslutningen om å transportere forespørselsparametere som et JSON-objekt, vil vi URL-kode parameteren for å sikre sikker transport.

Så for å sende følgende URL:

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

Vi ville faktisk gjort:

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

5. Begrensninger

La oss også huske begrensningene ved å sende et JSON-objekt som et sett med søkeparametere:

• redusert sikkerhet
• begrenset lengde på parametrene

For eksempel, jo flere data plasserer vi i en søkeparameter, jo mer vises i serverlogger og jo høyere er potensialet for sensitiv dataeksponering.

En enkelt spørringsparameter kan også ikke bestå av mer enn 2048 tegn. Gjerne kan vi alle forestille oss scenarier der JSON-objektene våre er større enn det. Praktisk sett en URL-koding av JSON-strengen vår vil faktisk begrense oss til ca 1000 tegn for nyttelasten vår.

En løsning er å sende større JSON-objekter i kroppen. På denne måten fikser vi både sikkerhetsproblemet og JSON-lengdebegrensningen.

Faktisk, FÅ eller POST begge støtter dette. En grunn til å sende et organ over GET er å opprettholde den RESTful semantikken til API-en vår.

Selvfølgelig er det litt uvanlig og støttes ikke universelt. For eksempel tillater enkelte JavaScript HTTP-biblioteker ikke at GET-forespørsler har en forespørsel.

Kort sagt, dette valget er en avveining mellom semantikk og universell kompatibilitet.

6. Konklusjon

For å oppsummere, i denne artikkelen lærte vi hvordan vi spesifiserer JSON-objekter som spørsmålsparametere ved hjelp av OpenAPI. Så observerte vi noen av implikasjonene på backend.

De komplette OpenAPI-definisjonene for disse eksemplene er tilgjengelige på GitHub.