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
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 }
La réponse d’une ressource de type élément contient deux types d’informations :
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" } }
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"}]