Spécification des réponses

Les API PMSIpilot utilisent le protocole HTTP.
Toutes les données sont retournées en JSON.
Les dates sont retournées au format AAAA-MM-JJ HH:MM:SS

Requête réussie

Si la requête réussit, la réponse retournée contient un code de statut HTTP de succès ainsi que le contenu attendu :

Code	Signification	Contenu
200	Requête réussie retournant du contenu.	Oui
201	Création réussie de ressource.	Non
204	Autre requête réussie ne retournant pas de contenu.	Non

Gestion des erreurs du client

Si la requête échoue, la réponse retournée contient un code de statut HTTP d'erreur du client :

Code	Signification	Contenu
400	Mauvais formatage de l'entité passée à la requête.	Non
401	Utilisateur non authentifié.	Non
403	Limite de requête atteinte.	Non
422	L'entité passée à la requête n'est pas satisfaisante.	Oui (voir ci-dessous)

Si l'entité passée à la requête n'est pas satisfaisante, le contenu de la réponse est du type :

HTTP/1.1 422 Unprocessable Entity
Content-Length: 175

{
  "message": "Une autre identité possède déjà l'IPP 321",
  "errors": [
    {
      "resource": "identites",
      "field": "ipp",
      "code": "already_exists"
    }
  ]
}

Toutes les erreurs disposent des champs resource et field afin que le client puisse remonter une erreur cohérente.
Un champ code est aussi présent pour préciser la nature du problème :

Code	Signification
missing	La ressource ciblée n'existe pas.
missing_field	Un champ obligatoire d'une ressource n'est pas présent dans l'entité.
invalid	Le format du champ est invalide.
already_exists	Un même champ d'une autre ressource contient déjà la même valeur que le champ de l'entité.

Headers HTTP personnalisés

Afin de ne pas poluer le contenu de la réponse HTTP, les API PMSIpilot retournent plusieurs informations annexes dans des headers personnalisés :

Last-Token

Contient la valeur du token généré par la modification de la ressource lors d'une requête d'écriture.
Contient la valeur du token utilisé pour modifier la plus récente ressource retournée lors d'une requête de lecture.

Fréquence : présent dans toutes les réponses de réquêtes réussies.

HTTP/1.1 200 OK
Status: 200 OK
Last-Token: 8459

RateLimit-Limit

Indique le nombre total d'appels possibles à l'API par heure et par utilisateur.

Fréquence : présent dans toutes les réponses.

HTTP/1.1 400 Bad Request
Status: 400 Bad Request
RateLimit-Limit: 5000

RateLimit-Remaining

Indique le nombre restant d'appels possibles à l'API par heure et par utilisateur.

Fréquence : présent dans toutes les réponses.

HTTP/1.1 400 Bad Request
Status: 400 Bad Request
RateLimit-Remaining: 224