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 [email protected]:test \
       "https://sandbox.clicrdv.com/api/v1/groups/4/interventions.xml?apikey=xxxxxx"

Récupérer un seul objet

Récupère l'agenda d’id 1 en format JSON:

$ curl -u [email protected]:test \
       "https://sandbox.clicrdv.com/api/v1/groups/4/calendars/1.json?apikey=xxxxxx"

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 [email protected]:test https://sandbox.clicrdv.com/api/v1/groups/4/calendars.json?apikey=xxxxxx \
       -X POST \
       -d '{"calendar":{"publicname":"","name":"Mike", "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"
}

La réponse du serveur a le code HTTP "201 Created", et pour contenu l’objet créé (avec en particulier l’id assigné à l’agenda créé).

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 [email protected]:test \
       -X PUT \
       -H 'Content-Type: application/json' \
       -d '{"calendar":{"name":"robert"}}' \
       "https://sandbox.clicrdv.com/api/v1/groups/4/calendars/6190.json?apikey=xxxxxx"

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 [email protected]:test \
       -X DELETE \
       https://sandbox.clicrdv.com/api/v1/groups/4/calendars/6190.json?apikey=xxxxxx&

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 [email protected]:test \
       -X POST \
       -H 'Content-Type: application/json' \
       -T newCalendar.json \
       "https://sandbox.clicrdv.com/api/v1/groups/4/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 "[email protected]:secret" \
       "https://sandbox.clicrdv.com/api/v1/groups/4/fiches.json?&apikey=xxxxxx"