Oggetti JSON OpenAPI come parametri di query

1. Panoramica

In questo tutorial impareremo come lavorare con oggetti JSON come parametri di query utilizzando OpenAPI .

2. Parametri di query in OpenAPI 2

OpenAPI 2 non supporta gli oggetti come parametri di query ; sono supportati solo i valori primitivi e gli array di primitive.

Per questo motivo, vorremo invece definire il nostro parametro JSON come una stringa.

Per vederlo in azione, definiamo un parametro chiamato params come una stringa , anche se lo analizzeremo come JSON nel nostro backend:

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" 

Quindi, invece di:

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

faremo:

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

3. Interrogare i parametri in OpenAPI 3

OpenAPI 3 introduce il supporto per gli oggetti come parametri di query.

Per specificare un parametro JSON, dobbiamo aggiungere una sezione di contenuto alla nostra definizione che includa il tipo e lo schema MIME:

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" 

La nostra richiesta può ora assomigliare a:

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

E, in realtà, può ancora sembrare:

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

La prima opzione ci consente di utilizzare le convalide dei parametri, che ci faranno sapere se qualcosa non va prima che venga effettuata la richiesta.

Con la seconda opzione, la scambiamo per un maggiore controllo sul back-end e per la compatibilità con OpenAPI 2.

4. Codifica URL

È importante notare che, nel prendere questa decisione di trasportare i parametri della richiesta come oggetto JSON, vorremo codificare in URL il parametro per garantire un trasporto sicuro.

Quindi, per inviare il seguente URL:

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

In realtà faremmo:

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

5. Limitazioni

Inoltre, teniamo a mente i limiti del passaggio di un oggetto JSON come set di parametri di query:

  • sicurezza ridotta
  • lunghezza limitata dei parametri

Ad esempio, più dati inseriamo in un parametro di query , più saranno visualizzati nei log del server e maggiore sarà il potenziale di esposizione dei dati sensibili.

Inoltre, un singolo parametro di query non può contenere più di 2048 caratteri. Certamente, tutti possiamo immaginare scenari in cui i nostri oggetti JSON sono più grandi di quello. In pratica, una codifica URL della nostra stringa JSON ci limiterà effettivamente a circa 1000 caratteri per il nostro payload.

Una soluzione alternativa consiste nell'inviare oggetti JSON di dimensioni maggiori nel corpo. In questo modo, risolviamo sia il problema di sicurezza che la limitazione della lunghezza di JSON.

In realtà, GET o POST lo supportano entrambi. Un motivo per inviare un corpo tramite GET è mantenere la semantica RESTful della nostra API.

Certo, è un po 'insolito e non universalmente supportato. Ad esempio, alcune librerie HTTP JavaScript non consentono alle richieste GET di avere un corpo della richiesta.

In breve, questa scelta è un compromesso tra semantica e compatibilità universale.

6. Conclusione

Per riassumere, in questo articolo abbiamo appreso come specificare oggetti JSON come parametri di query utilizzando OpenAPI. Quindi, abbiamo osservato alcune delle implicazioni sul backend.

Le definizioni OpenAPI complete per questi esempi sono disponibili su GitHub.