Curl

Curl est un client HTTP en ligne de commande. Comme l'API ClicRDV n’utilise que du HTTP, il se prête bien à l’utilisation avec ClicRDV.

Toutes les fonctionnalités de Curl sont également disponibles sous forme de librairie : libcurl. Il existe des bindings pour la plupart des langages de programmation.

Voici quelques exemples pour utiliser Curl sur l’API ClicRDV.

Notes : Dans les exemples ci-dessous, les ‘\’ en fin de ligne indiquent que le saut de ligne suivant ne correspond pas à un saut de ligne sur la ligne de commande.

Les options utilisées dans les exemples ci-dessous sont :

• -H ‘SomeHeader : value’: permet d’ajouter un header à la requête HTTP
• -u username:password : Authentification HTTP Basic
• -X method: méthode HTTP (GET, POST, PUT ou DELETE)
• -d ‘encoded content’: Contenu du corps de la requête (body dans le cas d’un POST ou d’un PUT)
• -T filename : Envoie le contenu du fichier filename dans le corps de la requête (body dans le cas d’un POST ou d’un PUT)
• -i : Affiche les headers de la réponse HTTP (en particulier les headers "Status" et "Set-Cookie")

Récupérer une liste d’objets

Récupère la liste des interventions en XML :

$ curl -u john@clicrdv.com:test \
       "https://sandbox.clicrdv.com/api/v1/interventions.xml?apikey=xxxxx"

Récupérer un seul objet

Récupère le calendrier d’id 1 en format JSON:

$ curl -u eric@clicrdv.com:test \
       "https://sandbox.clicrdv.com/api/v1/calendars/1.json?apikey=xxxxx"

Créer un nouvel objet

Important :

• Pour les requêtes POST et PUT, le header HTTP Content-Type doit être mis à application/json ou application/xml suivant l’encodage envoyé

• l’objet à créer doit être contenu dans un objet portant le nom au singulier de la collection (ex : ‘calendar’)

Exemple : création d’un agenda « Michel »

$ curl -u eric@clicrdv.com:test https://sandbox.clicrdv.com/api/v1/calendars.json \
       -d '{"apikey":"xxxx","calendar":{"publicname":"","name":"michel","group_id":4}}' \
       -H 'Content-Type: application/json'

Réponse :

{
   "name":"michel",
   "updated_at":"2010-03-15 17:50:22",
   "id":6189,
   "group_id":4,
   "sort":5,
   "publicname":"",
   "created_at":"2010-03-15 17:50:22"
}

Le serveur renvoie un code HTTP 201 Created, le contenu renvoie l’objet créé, contenant en particulier l’id assigné à l’agenda crée.

Modifier un objet

Important :

• Utiliser la méthode HTTP PUT
• le header HTTP Content-Type doit être mis à « application/json » ou « application/xml » suivant l’encodage choisit
• l’objet à créer doit être contenu dans un objet portant le nom au singulier de la collection (ex : ‘calendar’)
• Seul les champs modifiés peuvent être spécifiés

Exemple : Modification du nom de l’agenda d’id 6190 :

$ curl -u eric@clicrdv.com:test \
       -X PUT \
       -H 'Content-Type: application/json' \
       -d '{"calendar":{"name":"robert"},"format":"json","apikey":"xxxxx"}' \
       "https://sandbox.clicrdv.com/api/v1/calendars/6190"

Réponse : Renvoie l’objet dans sa totalité

{
   "name":"robert",
   "updated_at":"2010-03-15 17:56:13",
   "id":6190,
   "group_id":4,
   "sort":6,
   "publicname":"",
   "created_at":"2010-03-15 17:54:08"
}

Supprimer un objet

$ curl -u eric@clicrdv.com:test \
       -X DELETE \
       https://sandbox.clicrdv.com/api/v1/calendars/6190?apikey=xxxxx&format=json

Réponse :

• En cas de succès, le code HTTP renvoyé est « 200 OK ».

Le contenu de la réponse est vide.

• En cas d’erreur (tout code HTTP différent de 200), le corps de la réponse contiendra l’erreur. Par exemple en JSON:

[
 {
  "error":"You do not have access to this resource. (logged in as 'GroupAdmin' for resource 'calendars')"
 }
]

Créer un nouvel objet à partir d’un fichier

Créer un nouveau fichier appelé newCalendar.json avec le contenu suivant :

{"calendar":{"publicname":"","name":"essai","group_id":4}}

puis lancez la ligne de commande suivante :

$ curl -u eric@clicrdv.com:test \
       -X POST \
       -H 'Content-Type: application/json' \
       -T newCalendar.json \
       "https://sandbox.clicrdv.com/api/v1/calendars.json?apikey=xxxxxx"

Réponse :

{
   "name":"essai",
   "updated_at":"2010-03-15 18:04:34",
   "id":6191,
   "group_id":4,
   "sort":6,
   "publicname":"",
   "created_at":"2010-03-15 18:04:34"
}

Utilisation via un Proxy HTTP

Si vous devez vous connecter via un proxy HTTP, curl dispose d'un grand nombre d'options. (curl --help pour voir la liste des options disponibles). Par exemple :

$ curl --proxy my.host.com:8080 \
       -u "user@clicrdv.com:secret" \
       "https://www.clicrdv.com/api/v1/fiches.json?&apikey=xxxxxx"