Authentification API

Clé d’utilisation API

L’utilisation de l’API est restreinte par une clé d’utilisation. Les clés sont fournies sur demande par la société ClicRDV.

Les clés API sont différentes entre l’environnement « sandbox » et l’environnement de production.

La clé est associé à une application (vous devez demander plusieurs clés si vous créez plusieurs applications).

La clé doit être envoyée à chaque requête sur l’API, en utilisant le paramètre apikey.

Important : Veillez à encoder le paramètre apikey en utilisant le même format que les autres paramètres à envoyer (dépend du Content-Type envoyé par la requête.)

Par exemple, pour une requête GET envoyée avec le Content-Type « www-urlencoded » :

GET /api/v1/groups?apikey=xxxxxx

Pour une requête POST avec un Content-Type JSON :

POST /api/v1/groups/4/calendars
{
   apikey : "xxxxxx",
   calendar : {
     …
   }
}

Authentification

Pour l'accès aux ressources privées, vous devez vous authentifier en utilisant votre compte ClicRDV.

Il peut être utile d'ajouter un utilisateur dédié à l'utilisation de l'API.

Deux méthodes d'authentification sont disponibles :

• HTTP Basic : plus facile à utiliser, les identifiants sont envoyés à chaque requête. C'est la solution idéale si peu de requêtes successives sont envoyées.
• Session : nécessite une requête initiale pour récupérer un numéro de session, puis l'ajout d'un header HTTP dans les requêtes suivantes. Cette solution est préférable dans le cas d'un grand nombre de requêtes API successives.

HTTP Basic

L’API ClicRDV utilise une authentification HTTP Basic. Le mot de passe est encrypté dans la communication SSL du protocole HTTPS.

Avec Curl, vous pouvez spécifier l'utilisateur HTTP Basic en utilisant l'option -u :

$ curl -u "moncompte@clicrdv.com:secret" 
       "https://www.clicrdv.com/api/v1/fiches.json?apikey=xxxxx"

Avec la plupart des clients HTTP, le login/mot de passe peut-être envoyé dans l’URL. Exemple :

https://login:mdp@sandbox.clicrdv.com/api/v1/fiches.xml

Important : Dans la majorité des cas, « login » est une adresse email, le caractère ‘@’ doit être encodé par la séquence « %40 ». Exemple pour l’utilisateur eric@example.com :

https://eric%40example.com:mdp@sandbox.clicrdv.com/api/v1/fiches.xml

Sessions

Vous pouvez ouvrir une session grâce à la requête suivante :

POST http://www.clicrdv.com/api/v1/sessions/login

Les paramètres à envoyer dépendent du type d’utilisateur avec lequel vous vous connectez :

• Pour utiliser l’API de prise de RDV : account[email] et account[password]
• Pour utiliser l’API de Calendrier : pro[email] et pro[password]

Dans les deux cas, le mot de passe doit être encodé en SHA1. (Vous pouvez utiliser ce site pour rapidement convertir un mot de passe en SHA1)

Voici un exemple avec Curl :

$ curl -i -X POST  "https://sandbox.clicrdv.com/api/v1/sessions/login?\
                    pro%5Bemail%5D=fake.user%40gmail.com&\
                    pro%5Bpassword%5D=a94a8fe5ccb19ba61c4c0873d391e987982fbbd3&\
                    apikey=xxxxxx&format=json"

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Connection: keep-alive
Status: 200
X-Powered-By: Phusion Passenger (mod_rails/mod_rack) 3.0.7
ETag: "78fb55366f8233f1600d3e68ef789e11"
X-Runtime: 246
Content-Length: 283
Set-Cookie: _session_id=4e8c5362ed2abeddca00000c; path=/; HttpOnly

{"pro":{"created_at":"2007-03-30 15:09:07","updated_at":"2011-10-05 14:52:07",\
"synched_at":"2011-09-29 19:50:18","lastname":"Fake","isadmin_group":true,\
"id":9,"group_id":4,"funambol_cal_id":8,"firstname":"User",\
"cellphone":"06 12 34 56 78","email":"fake.user@gmail.com},"error":null}

(Les %5B et %5D correspondent aux caractères '[' et ']' encodés.)

L’identifiant de Session est renvoyé dans l’entête de réponse HTTP Set-Cookie. Ici :

…
Set-Cookie: _session_id=4e8c5362ed2abeddca00000c; path=/; HttpOnly
…

Pour les requêtes suivantes, il faut ensuite renvoyer dans le header Cookie le paramètre _session_id :

…
Cookie :_session_id=4e8c5362ed2abeddca00000c
…

Exemple avec Curl, l'option -H permettant d'ajouter un header HTTP :

$ curl -i -H 'Cookie: _session_id=4e8c5362ed2abeddca00000c' 
       "https://sandbox.clicrdv.com/api/v1/groups?format=json"

Note : Les sessions expirent au bout de 5 heures d’inactivité.