API HTTP & messages¶

API HTTP¶

L’API HTTP publique de l’application Zéphir est une vue partielle des messages transitant sur le routeur de messages. Elle utilise le format JSON.

Route de description de l’API¶

Une route publique api/v1 permet de lister les différents messages publics et de type RPC disponible dans l’API en version 1. Pour chaque message on dispose des informations suivantes :

uri

description

parameters

name

type

description

Liste complète des messages¶

v1

Points d’attention lors de la création d’un nouveau message¶

Privilégiez l’utilisation de paramètres nommés pour l’API de votre message.
Limitez les données transmises avec le message. Si possible utilisez des références plutôt que de passer l’entité.
Préferez le patron de conception « event » plutôt que le « rpc ».
Pensez à décrire votre message dans le répertoire common/messages/<version> et à passer l’attribut public à true si vous souhaitez voir votre message exposé sur l’API HTTP par le microservice api-bridge

Notes concernant les messages provenant de l’API HTTP¶

Tous les messages envoyés sur le bus de l’application Zéphir par le service api-bridge sont automatiquement préfixés par la version.

Exemple: Pour le message décrit dans services/common/messages/v1/example.calc.add.yml, l’URI du message sur le bus sera v1.example.calc.add.

Le service api-bridge ajoute également certains paramètres nommés aux messages qui transitent par lui:

_request_id String

Identifiant de la requête HTTP à l’origine du message. Pour la traçabilité des opérations, il est recommandé de transférer cet identifiant sur les messages qui pourraient être émis en cascade et d’afficher celui ci dans les journaux d’erreur et d’information.

Description du format YAML des messages¶

uri (obligatoire): Nom du message.
- Pour les messages de type RPC : l’URI de votre message devrait commencer par l”espace de nom du domaine fonctionnel de votre microservice suivi des éventuels sous-domaines et du verbe de l’action à réaliser (exemple: servermodel.create).
- Pour les messages de type Event : l’URI de votre message devrait commencer par l”espace de nom du domaine fonctionnel de votre microservice suivi des éventuels sous-domaines et de l’état du dernier sous-domaine (exemple: servermodel.created).
- Pour les messages de type erreur : l’URI de votre message devrait commencer par l”espace de nom du domaine fonctionnel de votre microservice suivi du mot « error » et du type d’erreur (exemple: servermodel.error.applicationservices).
description (obligatoire) : courte phrase de description du message en français. Respecter les majuscules et la ponctuation. Faire des phrases affirmatives (ni question, ni négation).
help : description plus conséquente (exemple d’utilisation, …)
sampleuse (obligatoire) : exemple d’utilisation avec zephir-client ou ~ s’il n’y a pas d’expemple à donner.
pattern (obligatoire) : choix entre rpc, event et error.
public : booléen permettant de conditionner la publication du message sur l’API du Zéphir (False par défaut).
domain (obligatoire) : espace de nom du domaine fonctionnel
parameters : dictionnaire des paramètres des messages de type RPC et Event. Chaque clé du dictionnaire des paramètres est le nom d’un paramètre en minuscule.
- type (obligatoire) : type du paramètre. Choisir parmi :
  - booléan : Boolean
  - nombre : Number
  - caractère : String
  - liste : []**type** (exemple : []Number)
  - dictionnaire : type personnalisé ou Dict (déconseillé)
- description (obligatoire) : courte phrase de description du paramètre en français. Respecter les majuscules et la ponctuation. Faire des phrases affirmatives (ni question, ni négation).
- help : description plus conséquente (exemple d’utilisation, …)
- default : valeur par défaut du paramètre. Si ce paramètre n’est pas spécifié, la valeur est obligatoire.
- ref : uri de l’entité stockant le paramètre (exemple : User.UserID)
response : dictionnaire des réponses des messages de type RPC. Chaque clé du dictionnaire des paramètres est le nom d’une réponse en minuscule.
- type (obligatoire) : type de la réponse. Choisir parmi :
  - booléan : Boolean
  - nombre : Number
  - caractère : String
  - liste : []**type** (exemple : []Number)
  - dictionnaire : type personnalisé ou Dict (déconseillé)
- description (obligatoire) : courte phrase de description du paramètre en français. Respecter les majuscules et la ponctuation. Faire des phrases affirmatives (ni question, ni négation).
- help : description plus conséquente (exemple d’utilisation, …)
- default : valeur par défaut du paramètre. Si ce paramètre n’est pas spécifié, la valeur est obligatoire.
- ref : uri du paramètre (exemple : servermodel.servermodelid)
errors : erreurs associés à ce message - uri (obligatoire) : URI du message d’erreur

Description d’un type personnalisé¶

Un type personnalisé permet de décrire les différentes clé d’un dictionnaire.

Chaque clé du dictionnaire est le nom d’un type en minuscule contenant les attributs suivants:

type (obligatoire) : type du paramètre. Choisir parmi :
- booléan : Boolean
- nombre : Number
- caractère : String
- liste : []**type** (exemple : []Number)
- dictionnaire : type personnalisé ou Dict (déconseillé)
description (obligatoire) : courte phrase de description du paramètre en français. Respecter les majuscules et la ponctuation. Faire des phrases affirmatives (ni question, ni négation).
help : description plus conséquente (exemple d’utilisation, …)
default : valeur par défaut du paramètre. Si ce paramètre n’est pas spécifié, la valeur est obligatoire.
ref : uri de l’entité stockant le paramètre (exemple :User.UserID)

Message type pour un domaine¶

Message	Événement	Retour
create	created	Retourne les informations de l’objet sans suivre les objets aggrégés (clés étrangères)
list		Retourne les informations de l’ensemble des objets dans suivre les objets aggrégés (clés étrangères)
delete	deleted	Retourne les informations de l’objet supprimé sans suivre les objets aggrégés (clés étrangères)
update	updated	Retourne les informations de l’objet mis à jour sans suivre les objets aggrégés (clés étrangères)
describe		Retourne les informations de l’objet en suivant les objets aggrégés (clés étrangères)