Enrichir le Payload à destination d'une API

L'objectif de la fonctionnalité PAYLOAD de l'API gateway Okapi est de pouvoir enrichir le body d'une requête à destination de l'API aussi bien au niveau de la déclaration d'une api ou de manière plus précise au sein d'une ressource.

Cas d'usages

Cette feature fait suite à une demande de l'API LIN qui a besoin de compléter le body des requêtes qui lui sont envoyées.

Principe de fonctionnement

L'API déclare dans son raccordement les éléments à ajouter au body de la requête provenant d'Okapi, sous le namespace payload dans les données optionnelles (extra).

La présence d'un objet JSON sous payload activera la fonctionnalité au niveau de l'API gateway si et seulement si, le body soumis dans la requête a la forme d'un objet (et pas la forme d'un tableau).

Le payload ajouté apparaît dans la requête initiée par Okapi à destination de l'API, défini par le Content-Type dans l'objet req.form, req.json ou par défaut req.body.

Configuration dans le raccordement de l'API

- type: api
  value:
    name: My Api
    urlContext: monapi
    version: '1'
    ...
    extra:
      payload:
        foo: bar
- type: resource
  value:
    name: My Resource
    api:
      urlContext: myapi
      version: "1"
    ...
    extra:
      payload:
        foo: bar

Comportement de la gateway

Le payload provenant d'une resource surdéfinit le contenu du payload de l'api.

Dans le cas où le payload de l'api est nécessaire au bon fonctionement de la ressource, il faudra le dupliquer dans le payload de resource.

Exemple

pré-requis:

• un serveur d'api (ouvert sur le port 3005) en local.
• le serveur de la gateway qui écoute en local.

Exemple d'API nommée "local" avec une ressource qui répond sur la route /hello:

- type: api
  value:
    published: true
    name: Local
    version: "1"
    urlContext: local
    extra:
      payload:
        fizz: buzz
    endpoint: "http://localhost:3005" # serveur local qui écoute le port 3005
    ownerUsername: provider
- type: resource
  value:
    name: Post Hello
    method: post
    route: /hello
    published: true
    extra:
      payload:
        foo: bar
    api:
      urlContext: local
      version: "1"

La requête suivante est envoyée par l'application d'un utilisateur d'Okapi:

http POST :3101/local/v1/hello name="my name"  X-Okapi-Key:< clé okapi à fournir>

Dans l'attribut req.body de la requête envoyée par Okapi à destination de la ressource de l'API, on peut recupérer le payload déclarée dans la configuration .yaml et celui de la requête initiale.

> api-test@0.0.0 start /Users/pierregorce/Documents/workspace/api-test
> node ./bin/www

{ name: 'my name', foo: 'bar' } # console.log(req.body)
POST /hello 204 11.953 ms - -