Refonte-Analyser le besoin pour le service web et créer un document de spécification
Quand on crée un service web interne, une application cliente va devoir échanger des données avec DIAPASON. Il va donc falloir lui spécifier comment communiquer avec DIAPASON ! 🤝
On va spécifier la structure des données d’échange entre DIAPASON et l’application cliente dans un document 📄 qui devra être transmis aux développeurs de l’application cliente.
Que doit-on mettre dans ce document ? On vous dit tout ! 👇
Qu’est ce que je dois écrire dans le document ? | C’est à dire ? | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
1-Introduction | |||||||||||||
Ce document présente et documente le Service Web qui permet … | Faites une petite présentation du Service Web : à quoi sert-il ? Quel est son cadre d’utilisation ? | ||||||||||||
2-Historique des modifications | |||||||||||||
Le tableau ci-dessous liste l’ensemble des modifications apportées au document.
| Vous pouvez renseigner les modifications du documents dans un tableau pour tracer les modifications de l’API. | ||||||||||||
3-Authentification | |||||||||||||
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 :
QWxhZGRpbjpvcGVuIHNlc2FtZQ== étant la représentation en Base64 du texte diapason:password. | L’authentification avec un identifiant et un mot de passe est obligatoire ! | ||||||||||||
4-Web Service | |||||||||||||
a-Formulation de la demande | |||||||||||||
Voici l’URL que <<<<< Nom du client >>>>> met à disposition pour l’utilisation du Service Web : OU ( si vous avez prévu d’utiliser des paramètres à la suite de l’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). | ||||||||||||
| C’est obligatoirement la méthode POST qu’on utilise ici ! | ||||||||||||
Le corps du message est au format Json. Il présentera les données d’entrée du service avec le formalisme suivant :
OU (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 est au format Json. Il doit impérativement contenir les informations "DIAP_METHODE" et « DIAP_DATA » sur le premier niveau tel que :
Pensez à préciser si les paramètres sont facultatifs ou optionnels ainsi que le type des paramètres. | ||||||||||||
| Donnez un exemple de contenu du corps du message (avec différents cas si possible). | ||||||||||||
b-Le retour | |||||||||||||
Réponse succès | |||||||||||||
Codes : 200 | |||||||||||||
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 :
| 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. | ||||||||||||
L’objet "DIAP_DATA" Voici la liste des paramètres de retour de l’objet "DIAP_DATA" :
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
NomDuChamp[type] : Description Les paramètres d’une liste sont fixes d’un élément de la liste à l’autre. L’ordre des éléments de la liste ne doit pas être pris en compte. | Le contenu de l’objet DIAP_DATA est à décrire avec les informations suivantes :
| ||||||||||||
{ "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 } ] } } | Donnez un exemple de contenu du corps du message (avec différents cas si possible). | ||||||||||||
Réponse Erreur | |||||||||||||
Erreurs type des services WEB Voici la liste des codes d’erreurs issus de Diapason avec le message associé :
| 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. | ||||||||||||
c-Caractéristiques complémentaires | |||||||||||||
Encodage : UTF-8
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" ) | Les caractéristiques complémentaires suivantes doivent impérativement être dans le document ! |
