Analyser le besoin pour le service web- Document modèle

La structure des données d’échange entre la REB et l’application cliente du service devra être transmise à l’équipe qui développera cette application (par le concepteur de la REB). Ce document permet de normaliser la description de l’API du service.

Préambule : Comment utiliser ce document

Ce document est un modèle pour permettre de fournir une description des échanges proposés par l’implémentation d’un Service Web Diapason Générique dans une REB.

La partie de la description « standard » est parfois optionnelle car elle peut dépendre des choix du paramétreur.

Le texte de couleur rouge ne devra pas apparaitre dans le document final de description de l’API !

Il conviendra donc de garder et de compléter le texte en vert ou dans des cadres vert.

Introduction

Faire une petite présentation du SW : son rôle et son cadre d’utilisation.

Ce document présente et documente le Service Web qui permet …

Historique des modifications

Le tableau ci-dessous permet de tracer les modifications de l’API.

Le tableau ci-dessous liste l’ensemble des modifications apportées au document.

Authentification

L’authentification avec un identifiant et un mot de passe est obligatoire dans l’outil SWDG.

Formalisme à mettre dans la description de l’API :

L’authentification s’effectue en méthode « Basic » définie par la spécification RFC 2617 : https://www.ietf.org/rfc/rfc2617.txt avec le login et le mot de passe d’un compte Diapason valide.

En résumé, pour s’authentifier, la requête cliente doit spécifier l'en-tête HTTP « Authorization ». Celle-ci doit contenir la méthode utilisée (Basic) suivie de la représentation en Base64 du nom de l'utilisateur et du mot de passe séparés par le caractère « : » (deux-points).

Par exemple, pour authentifier l'utilisateur « diapason » avec le mot de passe « password », le client envoie :

Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

QWxhZGRpbjpvcGVuIHNlc2FtZQ== étant la représentation en Base64 du texte diapason:password.

Web Service

Formulation de la demande

• URL

Sur une architecture standard, l’URL permettant d’utiliser le Service Web est celle du serveur HTTPS frontal que le client doit fournir et administrer.

Donnez l’URL permettant de lancer le service (sur le serveur frontal).

Exemple :

Voici l’URL que <<<<< Nom du client >>>>> met à disposition pour l’utilisation du Service Web :

https://NomClient.com/api/nomservice

Si vous avez prévu d’utiliser des paramètres à la suite de l’URL, donnez la description complète de l’URL et de ces paramètres comme dans l’exemple suivant :

Voici l’URL que <<<<< Nom du client >>>>> met à disposition pour l’utilisation du Service Web :

https://NomClient.com/api/nomservice?{Param1}=...t&{Param2}=...&{Param3}=...

Paramètres URL requis :

Param1[entier] : Description du paramètre 1

Param2[caractère] : Description du paramètre 2

Paramètres URL facultatifs :

Param3[caractère] : Description du paramètre 3

• Méthode

POST

• Corps du message

Le corps du message est au format Json. Il doit impérativement contenir les informations "DIAP_METHODE" et « DIAP_DATA » sur le premier niveau tel que :

DIAP_METHODE (caractère) : référence de la méthode de service web Diapason générique qui a été créé lors du paramétrage.

DIAP_DATA (Objet Json) : ensemble des paramètres d’entrée qui ne sont pas passés dans l’URL.

Pensez à préciser si les paramètres sont facultatifs ou optionnels ainsi que le type des paramètres.

Voici un modèle :

Le corps du message est au format Json. Il présentera les données d’entrée du service avec le formalisme suivant :

{

"DIAP_METHODE": "<<<Nom de la méthode de service web Diapason générique (défini dans Diapason)>>>",

"DIAP_DATA": {

"<<<Paramètre1>>>": "<<<Valeur du Paramètre1>>>",

"<<<Paramètre2>>>": "<<<Valeur du Paramètre2>>>",

"<<<Paramètre3>>>": <<<Valeur numérique du Paramètre3>>>

}

}

Paramètres requis :

Param1[caractère] : Description du paramètre 1

Param2[caractère] : Description du paramètre 2

Paramètres facultatifs :

Param3[décimal] : Description du paramètre 3

Si le Service Web n’a pas de paramètre ou si tous les paramètres sont donnés dans l’URL, le corps du message aura sa forme la plus simple comme ci-dessous :

Le corps du message est au format Json. Il présentera les données d’entrée du service avec le formalisme suivant :

{

"DIAP_METHODE": "<<<Nom de la méthode de service web Diapason générique (défini dans Diapason)>>>",

" DIAP_DATA": {}

}

Paramètres requis :

Aucun

Paramètres facultatifs :

Aucun

• Exemple de contenu

Donnez un exemple de contenu du corps du message (avec différents cas si possible).

Le retour

Réponse succès

• Codes de retour

Codes : 200

• Corps du message

Le corps du message est au format Json. Le premier niveau de paramètre sera toujours le même pour une même version de Diapason. Les paramètres provenant de la REB avec la fonction DIALOG « SW-DIAPASON » seront sur le premier niveau de l’objet DIAP_DATA.

Voici la description de la partie standard du corps du message :

Le corps du message est au format Json. Il présentera les données de retour du service avec le formalisme suivant :

Paramètres du premier niveau

Au premier niveau, l’objet « DIAP_DATA » contiendra toutes les informations de retour propre au service. Les autres paramètres de premier niveau sont des informations techniques pour la gestion et le suivi. La liste de ces autres paramètres pourra être agrémenté dans les versions futures de Diapason.

Voici la liste des éléments de premier niveau :

"DIAP_METHODE": "Nom de la méthode de service web Diapason générique (défini dans Diapason)",

"DIAP_IDENTIFIANT": "<<Identifiant unique de la requête de Service Web dans DIAPASON (GUID)>>",

"DIAP_STATUTS": "<<Statuts de sortie de la requête SUCCES ou ERROR>>",

"DIAP_DATA": { << Objet Json contenant les informations du service>> }

L’objet "DIAP_DATA"

Voici la liste des paramètres de retour de l’objet "DIAP_DATA" :

Le début de la description du corps du message est donc fixe. Le contenu de l’objet DIAP_DATA est à décrire par vous avec les informations suivantes :

• Pour un paramètre simple

Présentez les paramètres fixes et facultatif avec pour chaque élément :

Nom [type] : Description

Exemple :

Paramètres fixes :

Param1[caractère] : Description du paramètre 1

Param2[caractère] : Description du paramètre 2

Paramètres facultatifs :

Param3[décimal] : Description du paramètre 3

Pour un paramètre de type « liste »

Donnez le nom de la liste puis la description de son contenu :

NomDuChamp[type] : Description

Pour chaque liste, pensez à ajouter les informations suivantes :

Les paramètres d’une liste sont fixe d’un élément de la liste à l’autre.

L’ordre des éléments de la liste ne doit pas être pris en compte.

• Exemple

Donnez un exemple de contenu du corps du message (avec différents cas si possible).

Voici un exemple d’exemple :

{

"DIAP_METHODE": "Nom de la méthode de service web Diapason générique (défini dans Diapason)",

"DIAP_IDENTIFIANT": "<<Identifiant unique de la requête de Service Web dans DIAPASON (GUID)>>",

"DIAP_STATUTS":" SUCCES ",

"DIAP_DATA": {

"<<<Paramètre1>>>": "<<<Valeur du Paramètre1>>>",

"<<<Paramètre2>>>": "<<<Valeur du Paramètre2>>>",

"<<<Paramètre3>>>": "<<<Valeur numérique du Paramètre3>>>",

"<<<ExempleListe>>>": [

{

"ChampC": "ValCar1",

"ChampN": 45.0,

"ChampD": "2020-06-11",

"ChampL": false

},

{

"ChampC": "ValCar2",

"ChampN": 22.5,

"ChampD": "2020-06-10",

"ChampL": true

},

{

"ChampC": "ValCar3",

"ChampN": 15.0,

"ChampD": "2020-06-09",

"ChampL": false

}

]

}

}

Réponse Erreur

L’utilisation de l’instruction LC-ERREUR dans la REB génèrera un code 500 avec la description du LC-ERREUR dans l’élément « message ».

Vous devez donc ajouter et décrire la liste des erreurs gérées dans ce tableau.

Voici la liste des codes d’erreurs issus de Diapason avec le message associé :

Caractéristiques complémentaires

Les caractéristiques complémentaires suivantes doivent impérativement être dans le document final.

• Encodage

Encodage : UTF-8

• Format des données

Pour les valeurs de type numériques, le séparateur de décimale est le « . ».

Les valeurs logiques seront décrites par « true » ou « false ».

Les dates auront la forme suivante : <année>-<mois>-<jour> (exemple : "2020-06-30" )