API Reponse formats

HTTP response codes

Standard HTTP are respected. The HTTP response code is included in the HTTP response headers, and not in the response body.

  • 200 OK : everything went fine

  • 201 Created : the item has been created

Any other response code indicates an error. Here are the error codes that may occur :

  • 400 Bad Request : a parameter is missing or is invalid. The error details are generally included in the response body.

  • 401 Unauthorized : you are not allowed to access this resource, or the the login/password is wrong

  • 403 Forbidden : you don't have permission to do this operation

  • 404 Not Found : the resource does not exist, or you do not have access to it

  • 405 Method Not Allowed : the HTTP method is not available for this resource

  • 500 Internal Server Error : There is an issue with our application. Please contact us if this error occurs.

Response for collection resources

Requests that return multiple items will contain information about the pagination and sorting :

Field Type Description
records array Item list
sort string Sort field
dir string Sort direction ("asc" or "desc")
totalRecords integer Number of records matching the filter
startIndex integer Pagination start index
recordsReturned integer Number of records in this response
pageSize integer Maximum number of items per page (depends on results) 
{
  "records": [
     {
        "name":"un Conseiller ClicRDV",
        "updated_at":"2010-03-02 15:39:16",
        "created_at":"2007-03-27 12:20:46",
        …
     },
     …
  ],
  "dir":null,
  "sort":null,
  "totalRecords":1,
  "startIndex":0,
  "recordsReturned":1,
  "pageSize":25
}

XML responses are contained in a global hash object.

<?xml version="1.0" encoding="UTF-8"?>
<hash>
  <records type="array">
    <record>
      <name>un Conseiller ClicRDV</name>
      <created-at type="datetime">2007-03-27T12:20:46+02:00</created-at>
      <updated-at type="datetime">2010-03-02T15:39:16+01:00</updated-at>
    </record>
  </records>
  <dir nil="true"></dir>
  <sort nil="true"></sort>
  <totalRecords type="integer">1</totalRecords>
  <startIndex type="integer">0</startIndex>
  <recordsReturned type="integer">1</recordsReturned>
  <pageSize type="integer">25</pageSize>
</hash>

Response for member resources

Member resource contains two kinds of attributes :

  • The attributes of the item itself
  • Links to the collection resources linked to the item. The list of linked resources have a -ref suffix
    • api-ref : URL of the collection resource
    • href : name of the collection resource
{
  "name": "un Conseiller ClicRDV",
  "city": "Paris",
  "updated_at": "2010-03-02 15:39:16",
  "mailreminder": 0,
  "zipcode": "75019",
  "timezone": "Paris",
  "inactive": false,
  "country": "France",
  "id": 4,
  "phone": "01 83 62 04 04",
  "urlname": "rdv-clicrdv",
  "address": "14 rue de rouen",
  "created_at": "2007-03-27 12:20:46",
  "interventionsets-ref": {
      "api-ref": "/api/v1/groups/4/interventionsets",
      "href": "interventionsets"
  },
  "pros-ref": {
      "api-ref": "/api/v1/groups/4/pros",
      "href": "pros"
  },
  "interventions-ref": {
      "api-ref": "/api/v1/groups/4/interventions",
      "href": "interventions"
  },
  "calendars-ref": {
      "api-ref": "/api/v1/groups/4/calendars",
      "href":"calendars"
  },
  "fiches-ref": {
    "api-ref":"/api/v1/groups/4/fiches",
    "href":"fiches"
  },
  "calendarsets-ref": {
    "api-ref":"/api/v1/groups/4/calendarsets",
    "href":"calendarsets"
  }
}

The response is contained in an object with the same name as the resource collection in the singular. For example for the resource /api/v1/groups/4.xml :

<?xml version="1.0" encoding="UTF-8"?>
<group> 
  <name>un Conseiller ClicRDV</name>
  <city>Paris</city>
  <pros-ref>
    <api-ref>/api/v1/groups/4/pros</api-ref>
    <href>pros</href>
  </pros-ref>
  <updated-at type="datetime">2010-03-02T15:39:16+01:00</updated-at>
  <mailreminder type="integer">0</mailreminder>
  <interventionsets-ref>
    <api-ref>/api/v1/groups/4/interventionsets</api-ref>
    <href>interventionsets</href>
  </interventionsets-ref>
  <zipcode>75019</zipcode>
  <timezone>Paris</timezone>
  <inactive type="boolean">false</inactive>
  <country>France</country>
  <id type="integer">4</id>
  <interventions-ref>
    <api-ref>/api/v1/groups/4/interventions</api-ref> 
    <href>interventions</href>
  </interventions-ref>
  <phone>01 83 62 04 04</phone>
  <urlname>rdv-clicrdv</urlname>
  <calendars-ref> 
    <api-ref>/api/v1/groups/4/calendars</api-ref> 
    <href>calendars</href>
  </calendars-ref>
  <address>14 rue de rouen</address>
  <fiches-ref>
    <api-ref>/api/v1/groups/4/fiches</api-ref>
    <href>fiches</href>
  </fiches-ref>
  <calendarsets-ref>
    <api-ref>/api/v1/groups/4/calendarsets</api-ref>
    <href>calendarsets</href>
  </calendarsets-ref>
  <created-at type="datetime">2007-03-27T12:20:46+02:00</created-at>
</group>

API Error Messages

If the HTTP response code is different to 200 or 201, the response body will contain error details.

  [
    {"error":"Error message details here..."}
  ]
In XML, the records table will contain only one record element containing one or more error elements: 
<records type="array">
  <record>
    <error>Message d’erreur ici</error>
  </record>
</records>