OpenAPI 3.0 – Partie 4 
Utilisation de paramètres

Objectif de cet article

Nous allons ajouter un quatrième service à notre API TRQLEconomics, un service qui, et ce sera là toute la nouveauté, nécessitera le passage de paramètre(s).

Situation actuelle

Nous disposons d'une API de données économiques composée de 3 services. Aucun de ces services ne necessite le moindre passage de paramètres. Les services bankruptcies et corruption ont exactement la même structure pour ce qui concerne leur payload. Par contre, le payload de retour du service currencies a une structure différente. Ce ne sont que des détails mais ils sont intéressants pour ce qui est de notre définition de retour.

Petit avertissement

On se propose d'ajouter un 4ème service. Malheureusement, ce service n'a rien à voir avec des données économiques. On se permettra donc une petite exception pour les commodités de la démonstration en incluant ledit service dans l'API de base. Et vous ne m'en tiendrez aucune rigueur. Merci d'avance. Hihi.

Ajout du service Mercator

Ce service s'appelle ainsi en hommage au célèbre géographe, Gérard Mercator

Le service prend un seul paramètre : une chaîne de caractères tokenisée qui représente la latitude et la longitude. Je suis parfaitement d'accord … j'aurais probablement été mieux inspiré si je l'avais écrit pour traiter 2 paramètres. Dès lors, pour son intégration dans l'API, et comme base de démonstration pour la présente série d'articles, le code du service a été modifié de telle sorte qu'il puisse désormais accepter 1 paramètre ou 2.

Un service est un contrat

Tant qu'un service n'est pas publié il demeure volatile, changeant au possible. Dès le moment où il est publié, il devient intouchable. Plus ou moins intouchable. Son interface est intouchable, son retour aussi; pas nécessairement son immplémentation fonctionnelle.

Ainsi, faire en sorte que l'interface passe de 1 à 2 paramètres ce serait déroger au principe exposé ci-dessus. On ne devrait pas se le permettre. Par contre, l'idée directrice de l'invariabilité de l'interface est plus liée à la notion de compatibilité : si vous modifiez une interface mais gardez une stricte compatibilité avec une interface existante, vous respectez l'esprit de l'invariabilité. C'est ce que nous allons faire ici : on ajoute une interface possible tout en soutenant l'ancienne.

Interface à deux paramètres

Le code du service a donc été modifié pour fonctionner avec 1 paramètre ou 2. Le reste du service continuera à fonctionner comme précédemment.

Ici, dans OpenAPI, nous documenterons l'utilisation du service avec 2 paramètres.

Utilisation de paramètres dans les services

Pour définir un service avec des paramètres, il faut utiliser l'objet Parameter de OpenAPI.

Field Name	Type	Description
name	string	REQUIS. Nom du paramètre (sensible à la casse)
in	string	REQUIS. L'emplacement du paramètre. Les valeurs possibles sont query, header, path ou cookie.
description	string	Brève description du paramètre. La syntaxe CommonMark peut être utilisée pour des représentations textuelles riches.
required	boolean	Détermine si ce paramètre est obligatoire. Si l'emplacement du paramètre est path cette propriété est OBLIGATOIRE et sa valeur DOIT être true. Dans le cas contraire, la propriété PEUT être incluse et sa valeur par défaut est false.
deprecated	boolean	Spécifie qu'un paramètre est déprécié et qu'il DEVRAIT être retiré de la circulation.
allowEmptyValue	boolean	Définit la possibilité de transmettre des paramètres à valeur vide. Ceci n'est valable que pour les paramètres de requête et permet d'envoyer un paramètre avec une valeur vide. La valeur par défaut est false. Si le style est utilisé et si le comportement est n/a (ne peut pas être sérialisé), la valeur de allowEmptyValue DOIT être ignorée.

Définition du service mercator

Sur la base de ce qui a été défini dans la table ci-dessus, j'ai ajouté un path à notre YAML :

  /?mercator:
    get:
      summary: Récupérer les informations d'un point défini par une latitude et longitude
      parameters:
        - name: lat
          in: query
          description: La latitude de l'emplacement
          schema:
            type: number
        - name: lng
          in: query
          description: La longitude de l'emplacement
          schema:
            type: number
      responses:
        '200':
          description: Information détaillée à propos de l'emplacement défini par une latitiude et longitude 
          content:
            application/json:
              schema:
                type: object
                description: Le retour est un objet composé de deux objets, prolog et payload
                properties:
                  prolog:
                    $ref: "#/components/schemas/prolog"
                  payload:
                    type: object        # Différent comparé aux autres services

Ce qui nous donne…

Cet article est en construction !

YAML final pour 4 services

Voici la bouille de notre YAML :

openapi: 3.1.0
info:
  version: 0.0.1
  title: TRQL Radio economics-related services
  description: First version of the TRQLEconomics API featuring 3 services
  contact:
    email: pb@latosensu.be
  license:
      name: CC BY-SA 4.0 DEED Attribution-ShareAlike 4.0 International
      url: https://creativecommons.org/licenses/by-sa/4.0/
  termsOfService: https://www.trql.fm/tos/

servers:
  - url: https://www.trql.fm/vaesoli!
    description: Production Server

components:
  schemas:
    prolog:
      type: object
      description: metadonnées du service
      properties:
        service:
          type: string
        domain:
          type: string
        line:
          type: integer
        performance:
          type: number
        error:
          type: integer
        messages:
          type: array
        datetime:
          type: string
        cached:
          type: integer
        cacheDateTime:
          type: string
        ttl:
          type: integer
        callDateTime:
          type: integer
        copyright:
          type: string
        disclaimer:
          type: string
    payload:
      type: object
      description: véritable charge utile du retour (la cœur de la réponse)
      properties:
        entries:
          type: array       # entries est un tableau d'entrées

paths:
  /?bankruptcies:

    get:
      responses:
        '200':
          description: List of bankruptcies per country
          content:
            application/json:             # Retour en JSON
              schema:
                type: object              # L'objet de retour englobant le prolog et le payload
                description: Le retour est un objet composé de deux objets, prolog et payload
                properties:
                  prolog:
                    $ref: "#/components/schemas/prolog"
                  payload:
                    $ref: "#/components/schemas/payload"
  /?corruption:
    get:
      responses:
        '200':
          description: List of corruption index per country
          content:
            application/json:             # Retour en JSON
              schema:
                type: object              # L'objet de retour englobant le prolog et le payload
                description: Le retour est un objet composé de deux objets, prolog et payload
                properties:
                  prolog:
                    $ref: "#/components/schemas/prolog"
                  payload:
                    $ref: "#/components/schemas/payload"
  
  /?currencies:
    get:
      responses:
        '200':
          description: 9 conversion rates of currencies compared to EURO
          content:
            application/json:             # Retour en JSON
              schema:
                type: object              # L'objet de retour englobant le prolog et le payload
                description: Le retour est un objet composé de deux objets, prolog et payload
                properties:
                  prolog:
                    $ref: "#/components/schemas/prolog"
                  payload:
                    $ref: "#/components/schemas/payload"
  /?mercator:
    get:
      summary: Récupérer les informations d'un point défini par une latitude et longitude
      parameters:
        - name: lat
          in: query
          description: La latitude de l'emplacement
          schema:
            type: number
        - name: lng
          in: query
          description: La longitude de l'emplacement
          schema:
            type: number
      responses:
        '200':
          description: Information détaillée à propos de l'emplacement défini par une latitiude et longitude 
          content:
            application/json:             # Retour en JSON
              schema:
                type: object              # L'objet de retour englobant le prolog et le payload
                description: Le retour est un objet composé de deux objets, prolog et payload
                properties:
                  prolog:
                    $ref: "#/components/schemas/prolog"
                  payload:
                    type: object

Conclusion

Nous avons ajouté le service mercator, un service qui retourne une série d'informations de géolocalisation pour une latitude/longitude données. C'était notre objectif ! Il est rempli ! Ce service utilise des paramètres lancés dans le query string de l'appel de service : vous pouvez vous-même utilisé ce service directement dans votre navigateur : mercator !

À très bientôt et, surtout, pas de complication !

Liens utiles

• Swaggerhub
• OpenAPI Specification - version 3.0.1