✎ tecdoc:api [cynod]

Vous affichez une ancienne révision du document ! Si vous l'enregistrez, vous créerez une nouvelle version avec ce contenu.

====== API CYNOD ======

Ce document a pour objectif de présenter les API exposées par l’application CYNOD pour la gestion des fonctionnalités internes mais aussi de celles pour la mise en place de services à valeur ajouté de nos clients via les partenaires.

===== Vue d'ensemble =====
<color #ff7f27><schéma de présentation des différents composantes et de leurs interactions via API></color> **todo**

===== Sécurité =====
La sécurité de l’interface est principalement basée sur l’authentification ''oAuth2'' combinée au protocole ''https'' qui est le canal de communication par défaut des échanges. 
D’autres outils internes pourront être mis en place pour renforcer la sécurité tels que le filtrage d’adresse IP, les autorisations de ports et le VPN.
==== Identification ====
Les informations suivantes sont mises à la disposition des partenaires autorisés à envoyer des requêtes:
  - **//consumer-key//**
  - **//consumer-secret//**

//:!: Ces informations permettront aux partenaires de pouvoir s’authentifier.//
==== Authentification ====
L’authentification est gérée via le protocole ''oAuth2''.

Une fois connectés via l’API d’authentification, vous aurez un access_token qui vous permettra d’accéder aux autres ressources.
Les accès se feront en https.

//:!: Pour les partenaires qui le désirent, l'authentification peut être réalisée en ''Basic Authentication'' **que nous ne recommandons pas**.//

===== Principe général des échanges =====
Le format général des APIs respecte les principes ci-dessous :
  * Les données échangées sont au format ''JSON''.
  * La gestion des erreurs se base sur les codes ''statuts http'', et un code d’erreur interne selon les principe ci-dessous :

__**En cas de succès**__

* <code java>http status : 200 - OK</code>
  * payload json de réponse <code>{
    "success": "true",
    "code": "success code",
    "message":"success message to the application user",
    "data": "response data if necessary"
}</code>
__**En cas d'erreur fonctionnelle liée à la requête du client**__

* <code java>http status : 400 - Bad Request (Client Error)</code>
  * payload json avec le détail de l’erreur <code>{
    "success": "false",
    "code": "error code message to the app user",
    "debugMessage": "verbose message for debug purpose",
    "moreInfo": "null"
}</code>

__**En cas d'erreur d'authentification**__
  
  * <code java>http status : 401 - Unauthorized</code>

__**En cas d'erreur système lié à un problème serveur**__

* <code java>http status : 500 - Internal Server Error </code>
  * payload json avec le détail de l’erreur <code>{
    "success": "false"
    "code": "9999",
    "message": "message to the app user",
    "debugMessage": "verbose message for debug purpose"
}</code>

//:!: La description des données échangées est au format ''swagger''. Voir en annexe les différents codes d’erreur.//

/*
^ Cas                                                                               ^ Réponse                                                                                                                                                                                                                                                                                                  ^
| Succès                                                                            | http status : 200 - OK\\ payload json de réponse <code json>{    "success":       "true",     "code":           "success code",     "message":     "success message to the application user"     "data":            "response data if necessary” } </code>                                               |
| Erreur Fonctionnel\\ (En cas d’erreur fonctionnelle liée à la requête du client)  | http status : 400 - Bad Request (Client Error)/ 404 - Not Found - \\ payload json avec le détail de l’erreur <code json>{\\    "success": "false",\\    "code": "error code message to the app user",\\    "debugMessage": "verbose message for debug purpose",\\     "moreInfo": "null"\\ }\\  </code>  |
| Erreur Authentification                                                           | http status : 401 - Unauthorized                                                                                                                                                                                                                                                                         |
| Erreur Système\\ (En cas d’erreur système lié à un problème serveur)              | http status : 500 - Internal Server Error \\ payload json avec une indication de l’erreur <code json>{\\     “success”:false\\      "code": "9999",\\       "message": "message to the app user",\\       "debugMessage": "verbose message for debug purpose"\\ }\\ </code>                              |
*/
===== Base Core API =====
===== 3rd Party API =====
Cette section référence les API CYNOD qui sont mises à la disposition des partenaires pour construire des services digitaux au service de tous.
===== Principe général des échanges =====

Résumé

Note : En modifiant cette page, vous acceptez que le contenu soit placé sous les termes de la licence suivante : CC Attribution-Share Alike 4.0 International