====== Implémentation ======

Il est possible d'utiliser à peu près n'importe quel langage de programmation pour utiliser l'API. Nous donnons ci-après quelques exemples en langage Javascript, avec la librairie JQuery.

Les communications avec l'API passent par des requêtes HTTPS GET. Le format d'échange utilisé est le format JSON.

===== Authentification =====

**Preambule**

Deux standards sont employés dans le but de sécuriser l'API : 
  * HTTP Basic Authentication 
  * OAuth 2.0 JWT, avec échange de Token

**Principe général**
  - On commence par transmettre des informations d'authentification initiale à l'API (login et mot de passe). L'API vérifie les droits de la personne à utiliser l'API et, le cas échéant lui retourne un ''access_token'' et un ''refresh_token''.
  - Le ''access_token'' est un identifiant unique qui sert de laisser-passer pour tout appel ultérieur à l'API. Il a une durée de vie relativement courte (de l'ordre de l'heure). Au delà, un nouvel appel à l'API provoquera une erreur.
  - Le ''refresh_token'' sert à demander à l'API un nouvel ''access_token'', typiquement quand ce dernier a expiré. Il a donc une durée de vie beaucoup plus longue.
**
Pour en savoir plus sur JWT**
  * Référence [[https://tools.ietf.org/html/rfc7519|RFC 7519]]
  * Présentation sur [[https://jwt.io/introduction|jwt.io]]
  * Schémas illustrant l'échange de token sur [[https://blog.ippon.fr/2017/10/12/preuve-dauthentification-avec-jwt|ce billet de blog]].


===== Exemples avec la librairie JQuery (v3.5.1) =====

==== 1 - Authentification initiale ====

<code javascript | Authentification : /oauth/token>
$.ajax({
    method: 'POST',
    url: 'https://secure.bayard-service.com/annuaire_<MON_ANNUAIRE>/oauth/token',
    contentType: 'application/x-www-form-urlencoded; charset=utf-8',
    crossDomain:true,
    dataType: 'json',
    data: {
        grant_type: 'password',
        username: 'xxxxx',      // Login Adel
        password: 'xxxxx',      // Mot de passe Adel
        client_id: 'xxxxx',     // Basic-auth : id
        client_secret: 'xxxxx'  // Basic-auth : mot de passe
    },
    success: function (data) {
        console.log('success', data);
    },
    error: function (e) {
        console.log('error', e.responseText);
    }
});
</code>

Si l'authentification réussit, vous obtiendrez un retour de la forme :

<code json | Réponse>
{
 "access_token": "azertyiJIhyhyNiIsInR5cCI6IkpXVCJ9.eyJhdWQiOlsiand0cmVzb3VyY2VpZCJdLCJ1c2VyX25hbWUiOiJqbGFuZnJleSIsInNjb3BlIjpbInJlYWQiLCJ3cml0ZSIsInRydXN0Il0sImV4cCI6MTYxMjU0NDA1MSwiYXV0aG9yaXRpZXMiOlsic3lzX2dsb2JhbF9hZG1pbmlzdHJlciIsIlJPTEVfc3lzX2FkbWluIl0sImp0aSI6IjJiV1lwdEazertyXJ4Nm1hSSIsImNsaWVudF9pZCI6Imp3dGNsaWVudGlkIn0.x6gJRCbsOVVkpnsYduVL9QldGK0qPgW-Hql8mjcqBiQ",
 "token_type": "bearer",
 "refresh_token": "azertyzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOlsiand0cmVzb3VyY2VpZCJdLCJ1c2VyX25hbWUiOiJqbGFuZnJleSIsInNjb3BlIjpbInJlYWQiLCJ3cml0ZSIsInRydXN0Il0sImF0aSI6IjJiV1lwdEQ0QkdaSXJqaFplYTlpTXJ4Nm1hSSIsImF1dGhvcml0aWVzIjpbInN5c19nbG9iYWxfYWRtaW5pc3RyZXIiLCJST0xFX3N5c19hZG1pbiJdLCJqdGkiOiJvd1RkamQwZ3dUTU51MTg3ckNPRlRxT0ZwWHMiLCJjbGllbnRfaWQiOiJqd3RjbGllbnRpZCJ9.hT4WZ5yjloX5zH0Ko6c7WaTWD-ImGQYlmFxsInHVQqU",
 "expires_in": 3559,
 "scope": "read write trust",
 "jti": "azertyD4BGZIrjhZea9iMrx6maI"
}
</code>

==== 2 - Utilisation de l'API ====

Vous êtes désormais en mesure d'appeler les différentes routes de l'API en transmettant le ''access_token'' à chaque appel.

<code javascript | Appel de /api/v1/personnes/123>
$.ajax({
    method: 'GET',
    url: 'https://secure.bayard-service.com/annuaire_<MON_ANNUAIRE>/api/v1/personnes/123',
    dataType: 'json',
    crossDomain:true,
    data: {},
    beforeSend: function (xhr) {
        xhr.setRequestHeader('Authorization','Bearer ' + store.access_token);        
    },
    success: function (data) {
        console.log('success', data);
    },
    error: function (e) {
        console.log('error', e.responseText);
    }
});
</code>

Si vous utilisez votre ''access_token'' alors que ce dernier a expiré, qu'il n'est plus valide, vous obtiendrez un retour d'erreur de ce type :

<code json | Utilisation d'un access_token invalide>
{"error":"invalid_token","error_description":"Access token expired: azertyiJIhyhyNiIsInR5cCI6IkpXVCJ9.eyJhdWQiOlsiand0cmVzb3VyY2VpZCJdLCJ1c2VyX25hbWUiOiJqbGFuZnJleSIsInNjb3BlIjpbInJlYWQiLCJ3cml0ZSIsInRydXN0Il0sImV4cCI6MTYxMjU0NDA1MSwiYXV0aG9yaXRpZXMiOlsic3lzX2dsb2JhbF9hZG1pbmlzdHJlciIsIlJPTEVfc3lzX2FkbWluIl0sImp0aSI6IjJiV1lwdEazertyXJ4Nm1hSSIsImNsaWVudF9pZCI6Imp3dGNsaWVudGlkIn0.x6gJRCbsOVVkpnsYduVL9QldGK0qPgW-Hql8mjcqBiQ"}
</code>

==== 3 - Actualisation du ''access_token'' ====

Si votre ''access_token'' est invalide, vous devez en demander un nouveau en utilisant le ''refresh_token''.

<code javascript | Actualisation du token : /oauth/token>
$.ajax({
    method: 'POST',
    url: 'https://secure.bayard-service.com/annuaire_<MON_ANNUAIRE>/oauth/token',
    contentType:'application/x-www-form-urlencoded; charset=utf-8',
    data: {
        grant_type: 'refresh_token',
        refresh_token: store.refresh_token, // Le refresh_token
        client_id: 'xxxxx',                 // Basic-auth : id
        client_secret: 'xxxxx'              // Basic-auth : mot de passe
    },
    success: function (data) {
        console.log('success', data);
    },
    error: function (e) {
        console.log('error', e.responseText);
    }
});
</code>

Le retour est similaire à celui obtenu lors de l'authentification initiale.