Curl

Curl is a HTTP client command line. As the ClicRDV API only uses HTTP, it is well suited for use with ClicRDV.

All the functionalities of Curl are also available in the form of a library: libcurl. There are bindings for the majority of programming languages.

Here are some examples to use Curl on the ClicRDV API.

Please note: In the examples below, the ‘\’ end of the line indicates the newline following does not match a newline on the command line.

The options used in the examples below are:

• -H ‘SomeHeader : value’: you can add a header to the http request
• -u username:password : user name and password to use for server HTTP Basic authentication
• -X method: HTTP method (GET, POST, PUT or DELETE)
• -d ‘encoded content’: content of the request body (POST or PUT)
• -T filename : transmission of the contents of the file filename in the request body (POST or PUT)
• -i : displays the http response headers (especially "Status" and "Set-Cookie")

Retrieve a list of objects

Retrieve the list of interventions in XML:

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

Retrieve a single object

Retrieve the calendar whose id is 1 in JSON format:

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

Create a new object

Important :

• For the POST and PUT queries, the HTTP Content-Type header must be set to application/json or application/xml according to the transmitted encoding.

• The object to be created must be wrapped in an object with the singular name of the collection (e.g. ‘calendar’)

Example: creation of a calendar "Mike"

$ 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'

Response:

{
   "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"
}

The server responds with the HTTP code "201 Created", and with the created object as the body (containing the id assigned to the calendar created).

Modify an object

Important :

• Use the HTTP method PUT
• The HTTP Content-Type header must be set to « application/json » or « application/xml » according to the encoding chosen
• The object to be created must be wrapped in an object with the singular name of the collection (e.g. ‘calendar’)
• Only the modified fields can be specified

Example : modify the name of the agenda whose id is 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"

Response: the whole object is returned

{
   "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"
}

Delete an object

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

Response:

• In case of success, the returned HTTP code is « 200 OK ». The contents of the response is empty.
• In case of error (any HTTP code different from 200), the response body will contain an error. For example in JSON:

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

Create a new object from a file

Create a new file named newCalendar.json containing the following:

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

Then launch the following command line:

$ 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"

Response:

{
   "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"
}

Use via a HTTP Proxy

If you need to connect via a HTTP proxy, curl has many options. (curl --help to see the list of available options). For example:

$ curl --proxy my.host.com:8080 \
       -u "[email protected]:secret" \
       "https://sandbox.clicrdv.com/api/v1/groups/4/fiches.json?&apikey=xxxxxx"