Objets JSON OpenAPI en tant que paramètres de requête

1. Vue d'ensemble

Dans ce didacticiel, nous allons apprendre à utiliser des objets JSON en tant que paramètres de requête à l'aide d'OpenAPI .

2. Paramètres de requête dans OpenAPI 2

OpenAPI 2 ne prend pas en charge les objets en tant que paramètres de requête ; seules les valeurs primitives et les tableaux de primitives sont pris en charge.

Pour cette raison, nous souhaitons plutôt définir notre paramètre JSON sous forme de chaîne.

Pour voir cela en action, définissons un paramètre appelé params sous forme de chaîne , même si nous l'analyserons en JSON dans notre 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" 

Ainsi, au lieu de:

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

nous allons faire:

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

3. Paramètres de requête dans OpenAPI 3

OpenAPI 3 introduit la prise en charge des objets en tant que paramètres de requête.

Pour spécifier un paramètre JSON, nous devons ajouter une section de contenu à notre définition qui inclut le type et le schéma 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" 

Notre demande peut maintenant ressembler à:

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

Et, en fait, cela peut toujours ressembler à:

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

La première option nous permet d'utiliser des validations de paramètres, qui nous permettront de savoir si quelque chose ne va pas avant que la demande ne soit faite.

Avec la deuxième option, nous échangeons cela pour un meilleur contrôle sur le backend ainsi que pour la compatibilité OpenAPI 2.

4. Encodage d'URL

Il est important de noter que, en prenant cette décision de transporter les paramètres de demande en tant qu'objet JSON, nous voudrons encoder l'URL du paramètre pour assurer un transport sûr.

Donc, pour envoyer l'URL suivante:

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

Nous ferions en fait:

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

5. Limitations

Gardons également à l'esprit les limites du passage d'un objet JSON en tant qu'ensemble de paramètres de requête:

  • sécurité réduite
  • longueur limitée des paramètres

Par exemple, plus nous plaçons de données dans un paramètre de requête , plus il apparaît dans les journaux du serveur et plus le potentiel d'exposition des données sensibles est élevé.

En outre, un seul paramètre de requête ne peut pas dépasser 2 048 caractères. Certes, nous pouvons tous imaginer des scénarios où nos objets JSON sont plus grands que cela. En pratique, un encodage URL de notre chaîne JSON nous limitera en fait à environ 1000 caractères pour notre charge utile.

Une solution de contournement consiste à envoyer des objets JSON plus volumineux dans le corps. De cette façon, nous corrigeons à la fois le problème de sécurité et la limitation de longueur JSON.

En fait, GET ou POST le supportent tous les deux. Une des raisons d'envoyer un corps via GET est de maintenir la sémantique RESTful de notre API.

Bien sûr, c'est un peu inhabituel et pas universellement pris en charge. Par exemple, certaines bibliothèques HTTP JavaScript n'autorisent pas les requêtes GET à avoir un corps de requête.

Bref, ce choix est un compromis entre sémantique et compatibilité universelle.

6. Conclusion

Pour résumer, dans cet article, nous avons appris à spécifier des objets JSON en tant que paramètres de requête à l'aide d'OpenAPI. Ensuite, nous avons observé certaines des implications sur le backend.

Les définitions OpenAPI complètes de ces exemples sont disponibles à l'adresse over sur GitHub.