Réponses API

Codes HTTP

Tous les codes du standard HTTP sont respectés au maximum. Le code de réponse HTTP est contenu dans l’entête HTTP, et non dans le contenu de la réponse. La récupération de ce code dépend donc du client HTTP utilisé.

  • 200 OK : tout s’est bien passé

  • 201 Created : un objet a été créé avec succès

Tous les autres codes indiquent que quelque chose s’est mal passé.

Les codes d’erreurs que vous êtes susceptibles de voir sont :

  • 400 Bad Request : un paramètre de requête est manquant ou erroné. Le message d’erreur associé vous indique généralement le problème

  • 401 Unauthorized : vous n’êtes pas authentifié ou le couple login/mot de passe est erroné

  • 403 Forbidden : vous n’avez pas la permission requise pour exécuter cette opération

  • 404 Not Found : la ressource demandée n’existe pas, ou vous n’y avez pas accès

  • 405 Method Not Allowed : vous avez utilisé une méthode HTTP non disponible sur la ressource

  • 500 Internal Server Error : un problème est survenu au sein de l’application ClicRDV; si cette erreur persiste, merci de nous contacter

Réponse des ressources de type collection

Les réponses sur les ressources collection sont paginées. (Par défaut, l’API ClicRDV renvoie les 25 premiers éléments.)

La réponse contient donc des informations relatives à la pagination, mais aussi au tri :

Champ Type Description
records array Liste des éléments
sort string Champ par lequel la liste est triée
dir string Direction du tri ("asc" ou "desc")
totalRecords integer Nombre total d’éléments correspondant aux filtres
startIndex integer Index de début de la pagination
recordsReturned integer Nombre d’éléments retournés dans la liste
pageSize integer Nombre d’éléments par page (suivant le paramètre de requête results)

Format XML

Les réponses XML sont contenues dans un objet global hash.

<?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>

Format JSON

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

Réponse des ressources de type member

La réponse d’une ressource de type élément contient deux types d’informations :

  • La liste des attributs de cet élément et les valeurs associées
  • La liste des ressources de types collection liées à cet élément
    • Les liste de ressources liées sont suffixées par « -ref »
    • Leur valeur est un objet contenant deux attributs :
      • api-ref : l’URL relative de la ressource collection
      • href : nom de la ressource collection

Format XML

La réponse est contenue dans un objet portant le même nom que la ressource collection au singulier. Par exemple pour la ressource /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>

Format JSON

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

Messages d’erreurs de l’API

En cas de code HTTP différent de 200 ou 201, le contenu de la réponse contiendra une liste d'une ou plusieurs erreurs.

En XML, le tableau records ne contiendra qu’un seul élément record contenant un ou plusieurs éléments error :

<records type="array">
  <record>
    <error>Message d’erreur ici</error>
  </record>
</records>

En JSON, un simple tableau avec la liste des erreurs sera renvoyée :

[{"error":"Message d’erreur ici"}]