OpenAPI JSON objekti kao parametri upita

1. Pregled

U ovom uputstvu naučit ćemo kako raditi JSON objekti kao parametri upita pomoću OpenAPI.

2. Parametri upita u OpenAPI 2

OpenAPI 2 ne podržava objekte kao parametre upita; podržane su samo primitivne vrijednosti i nizovi primitiva.

Zbog toga ćemo umjesto toga željeti definirati naš JSON parametar kao niz.

Da bismo to vidjeli na djelu, definirajmo parametar tzv parametarima kao niz, iako ćemo ga raščlaniti kao JSON u našem backendu:

swagger: "2.0" ... staze: / ulaznice: get: tagovi: - sažetak "ulaznice": "Pošaljite JSON objekt kao parametar upita" parametri: - ime: "params" u: "opis" putanje: "{ \ "type \": \ "foo \", \ "color \": \ "green \"} "potrebno: true type:" string "

Dakle, umjesto:

GET // localhost: 8080 / api / ulaznice? Type = foo & color = green

napravit ćemo:

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

3. Upitajte parametre u OpenAPI 3

OpenAPI 3 uvodi podršku za objekte kao parametre upita.

Da bismo odredili JSON parametar, trebamo dodati a sadržaj odjeljak naše definicije koji uključuje MIME tip i shemu:

openapi: 3.0.1 ... staze: / ulaznice: get: oznake: - sažetak ulaznica: Pošaljite JSON objekt kao parametre parametara upita: - ime: parametar u: opis upita: '{"type": "foo", "color": "green"} 'obavezno: true schema: type: property properties: type: type: "string" color: type: "string"

Naš zahtjev sada može izgledati ovako:

GET // localhost: 8080 / api / ulaznice? Params [vrsta] = foo¶ms [boja] = zelena

I zapravo, još uvijek može izgledati kao:

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

Prva opcija omogućuje nam upotrebu provjera parametara, koje će nas obavijestiti ako nešto nije u redu prije nego što se podnese zahtjev.

S drugom opcijom trgujemo za veću kontrolu nad pozadinom, kao i za kompatibilnost OpenAPI 2.

4. URL kodiranje

Važno je napomenuti da ćemo prilikom donošenja ove odluke o prijenosu parametara zahtjeva kao JSON objekta htjeti URL-kodirati parametar kako bismo osigurali siguran transport.

Dakle, za slanje sljedećeg URL-a:

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

Zapravo bismo napravili:

GET / ulaznice? Parametar =% 7B% 22tip% 22% 3A% 22foo% 22% 2C% 22boja% 22% 3A% 22zelena% 22% 7D

5. Ograničenja

Također, imajmo na umu ograničenja prosljeđivanja JSON objekta kao skupa parametara upita:

smanjena sigurnost
ograničena duljina parametara

Na primjer, što više podataka stavimo u parametar upita, više se pojavljuje u zapisima poslužitelja i to je veća mogućnost izloženosti osjetljivim podacima.

Također, jedan parametar upita ne može biti duži od 2048 znakova. Svakako, svi možemo zamisliti scenarije u kojima su naši JSON objekti veći od toga. Praktično govoreći, URL kodiranje našeg JSON niza zapravo će nas ograničiti na oko 1000 znakova za našu nosivost.

Jedno zaobilazno rješenje je slanje većih JSON objekata u tijelo. Na taj način rješavamo i sigurnosni problem i ograničenje duljine JSON-a.

Zapravo, GET ili POST oba podržavaju ovo. Jedan od razloga za slanje tijela preko GET-a je održavanje RESTful semantike našeg API-ja.

Naravno, pomalo je neobičan i nije univerzalno podržan. Na primjer, neke JavaScript HTTP knjižnice ne dopuštaju da GET zahtjevi imaju tijelo zahtjeva.

Ukratko, ovaj izbor predstavlja kompromis između semantike i univerzalne kompatibilnosti.

6. Zaključak

Da sumiramo, u ovom smo članku naučili kako odrediti JSON objekte kao parametre upita pomoću OpenAPI-a. Zatim smo primijetili neke implikacije na pozadinu.

Kompletne definicije OpenAPI za ove primjere dostupne su na GitHubu.

streamalism.org