Premiers pas

Préambule

L'API ici présentée est une API de type REST fortement inspirée de celle d'OVH.

Pour être en mesure de l'utiliser, il faut comprendre la philosophie REST (c.f. Wikipedia) et comprendre comment fonctionne le mécanisme d'authentification présentée ci-dessous.

L'API s'appuie donc sur le protocole HTTP 1.1, et consiste en requêtes classiques (e.g. GET) avec au moins les entêtes suivants envoyés par le client à chaque requête (qui seront décrits plus bas):

• X-Triethic-MTimestamp
• X-Triethic-Application
• X-Triethic-Signature
• X-Triethic-Consumer

Mécanisme d'authentification

Pré-requis

Afin d'être en mesure d'utiliser l'API, il faut impérativement

• trois clefs fournies par Triethic :
  • le code client ; noté dans le reste de ce document CK, et est associé à l'entête X-Triethic-Consumer
  • le code application ; noté dans le reste de ce document AK, et est associé à l'entête X-Triethic-Application
  • le code secret ; noté dans le reste de ce document AS
• un TIMESTAMP en msec ; notée dans le reste de ce document TSTAMP, et est associé à l'entête X-Triethic-MTimestamp
  Il s'agit d'un timestamp UNIX en milliseconde qui devra être récupéré juste avant d'envoyer la requête au serveur et avant la génération de la signature puisqu'il participe à la génération de ladite signature.
  À chaque requête le timestamp est stocké et l'API s'attend à ce que le prochain timestamp soit strictement supérieur au précédent. Ce mécanisme est utilisé pour éviter que les requêtes soient rejouées.

Génération de la signature

L'entête de message X-Triethic-Signature sera à générer de la manière suivante :

$d = [ //Nous récupérons ici les données envoyées en entête par le client
    'TSTAMP'       => $request->header('X-Triethic-MTimestamp'),
    'AK'           => $request->header('X-Triethic-Application'),
    'CK'           => $request->header('X-Triethic-Consumer'),
    'SIG'          => $request->header('X-Triethic-Signature')
];
$signature = '$1$' . hash('SHA1', $d['AS'].'+'.$d['CK'].'+'.$d['TSTAMP']);

Comme le suggère le code (pour les amateurs de PHP) :

• les AS, CK, TSTAMP, RD sont concaténés et reliés par le caractère +
• le résultat de la concaténation est hashé avec l'algorithme SHA1, ET est converti en chaîne de caractère ; attention ce comportement est spécifique à la fonction hash de PHP
• et pour finir, la signature est le résultat de la concaténation de la chaîne $1$ avec le « hash hexadécimal » obtenu à l'étape précédente

Tambouille finale

Pour qu'une requête présentée au serveur soit acceptée il faut :

• qu'il n'y ait au plus qu'une seconde d'écart entre le moment où la requête est générée par le client et est reçue par le serveur
  Nous vous conseillons donc de synchroniser votre client avec l'un des nombreux serveurs de temps disponibles sur internet, ou, si vous ne pouvez pas le faire, utilisez l'appel v1.0/auth/time (c.f. l'appel lui-même) pour calculer un delta.
• un appel à une des méthodes de l'API, en respectant le type de méthode attendues, les paramètres éventuels, etc
• ajouter à vos requêtes les bons entêtes qui permettent d'identifier votre code
• ajouter la signature correctement construite à vos entêtes

Examples

Prenons l'exemple des données suivantes :

X-Triethic-Application => 7kbG7Bk7S9Nt7ZSV
X-Triethic-Consumer    => MtSwSrPpNjqfVSmJhLbPyr2i45lSwPU1
AS                     => kjdhfgkjdfhgkjdfhgjkdfh

Shell Linux

Ce premier exemple illustre la manière de vérifier que tout est bien opérationnel en ce qui concerne l'authentification grâce à l'appel v1.0/auth/check (c.f. l'appel lui-même)

export TIMESTAMP=$(date '+%s%3N') ;  curl -X GET \
                                       -H "X-Triethic-MTimestamp: $TIMESTAMP" \
                                       -H 'X-Triethic-Application: 7kbG7Bk7S9Nt7ZSV' \
                                       -H 'X-Triethic-Signature: $1$'$(echo -n "kjdhfgkjdfhgkjdfhgjkdfh+MtSwSrPpNjqfVSmJhLbPyr2i45lSwPU1+$TIMESTAMP+kjfdkljsdflkgjdlkfjglskdjfg" | sha1sum | cut -f 1 -d ' ') \
                                       -H 'X-Triethic-Consumer: MtSwSrPpNjqfVSmJhLbPyr2i45lSwPU1' \
                                       -i 'https://api.portail.icionrecycle.fr/api/v1.0/auth/check'

Le programme ApIOR

Afin de vous aider à utiliser et tester l'API nous avons réalisé une application facile à utiliser permettant d'interroger notre serveur.
Voici une capture d'écran de d'application :

ApIOR

Le code source : apior-1_0_0_0-src.7z
Le binaire (Microsoft CRT 2015 x64 bits ) : apior-1_0_0_0-bin.7z

Le mot de la fin

Pour vérifier que vous savez effectivement envoyer des données, et utiliser l'API, nous vous renvoyons à la lecture de v1.0/auth/check (c.f. l'appel lui-même) qui a été conçue à cette fin.