-
Notifications
You must be signed in to change notification settings - Fork 2
/
specification-reponses.html
122 lines (113 loc) · 5.58 KB
/
specification-reponses.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
<!DOCTYPE html>
<html lang="fr">
<head>
<title>API PMSIpilot</title>
<meta charset="utf-8">
<script type="text/javascript" src="js/jquery-1.7.1.min.js"></script>
<script type="text/javascript" src="js/api.js"></script>
<link rel="stylesheet" href="css/bootstrap.min.css">
<link rel="stylesheet" href="css/base.css">
</head>
<body>
<div class="topbar">
<div class="fill">
<div class="container">
<a class="brand" href="index.html">Présentation</a>
<a class="brand" href="documentation.html">Documentation</a>
<a class="brand" href="http://www.pmsipilot.com/fr/contact">Contact</a>
</div>
</div>
</div>
<div class="container">
<div id="breadcrumbs">
<div class="breadcrumb">
<a href="documentation.html">Documentation</a> → <a href="">Spécification des réponses</a>
</div>
</div><!-- end #breadcrumbs -->
<div class="content row">
<div class="span12">
<h1 id="title">Spécification des réponses</h1>
<p>Les API PMSIpilot utilisent le protocole <a href="http://fr.wikipedia.org/wiki/Hypertext_Transfer_Protocol" title="HTTP">HTTP</a>.<br />
Toutes les données sont retournées en <a href="http://fr.wikipedia.org/wiki/JavaScript_Object_Notation" title="JSON">JSON</a>.<br />
Les dates sont retournées au format <code>AAAA-MM-JJ HH:MM:SS</code></p>
<h2 id="requete-reussie">Requête réussie</h2>
<p>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 :</p>
<table>
<thead><tr><th>Code</th><th>Signification</th><th>Contenu</th></tr></thead>
<tbody>
<tr><td>200</td><td>Requête réussie retournant du contenu.</td><td>Oui</td></tr>
<tr><td>201</td><td>Création réussie de ressource.</td><td>Non</td></tr>
<tr><td>204</td><td>Autre requête réussie ne retournant pas de contenu.</td><td>Non</td></tr>
</tbody>
</table>
<h2 id="erreur-client">Gestion des erreurs du client</h2>
<p>Si la requête échoue, la réponse retournée contient un code de statut HTTP d'erreur du client :</p>
<table>
<thead><tr><th>Code</th><th>Signification</th><th>Contenu</th></tr></thead>
<tbody>
<tr><td>400</td><td>Mauvais formatage de l'entité passée à la requête.</td><td>Non</td></tr>
<tr><td>401</td><td>Utilisateur non authentifié.</td><td>Non</td></tr>
<tr><td>403</td><td><a href="specification-requetes.html#limitation">Limite de requête</a> atteinte.</td><td>Non</td></tr>
<tr><td>422</td><td>L'entité passée à la requête n'est pas satisfaisante.</td><td>Oui (voir ci-dessous)</td></tr>
</tbody>
</table>
<p>Si l'entité passée à la requête n'est pas satisfaisante, le contenu de la réponse est du type :</p>
<pre class="highlight">
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"
}
]
}</pre>
<p>Toutes les erreurs disposent des champs <strong>resource</strong> et <strong>field</strong> afin que le client puisse remonter une erreur cohérente.<br />Un champ <strong>code</strong> est aussi présent pour préciser la nature du problème :</p>
<table>
<thead><tr><th>Code</th><th>Signification</th></tr></thead>
<tbody>
<tr><td>missing</td><td>La ressource ciblée n'existe pas.</td></tr>
<tr><td>missing_field</td><td>Un champ obligatoire d'une ressource n'est pas présent dans l'entité.</td></tr>
<tr><td>invalid</td><td>Le format du champ est invalide.</td></tr>
<tr><td>already_exists</td><td>Un même champ d'une autre ressource contient déjà la même valeur que le champ de l'entité.</td></tr>
</tbody>
</table>
<h2 id="headers-personnalises">Headers HTTP personnalisés</h2>
<p>Afin de ne pas poluer le contenu de la réponse HTTP, les API PMSIpilot retournent plusieurs informations annexes dans des headers personnalisés :</p>
<h4 id="last-token">Last-Token</h4>
<p>
Contient la valeur du token généré par la modification de la ressource lors d'une requête d'écriture.<br />
Contient la valeur du token utilisé pour modifier la plus récente ressource retournée lors d'une requête de lecture.
</p>
<p></p><strong>Fréquence</strong> : présent dans toutes les réponses de réquêtes réussies.</p>
<pre>
HTTP/1.1 200 OK
Status: 200 OK
Last-Token: 8459</pre>
<h4 id="ratelimit-limit">RateLimit-Limit</h4>
<p>Indique le nombre total d'appels possibles à l'API par heure et par utilisateur.</p>
<p></p><strong>Fréquence</strong> : présent dans toutes les réponses.</p>
<pre>
HTTP/1.1 400 Bad Request
Status: 400 Bad Request
RateLimit-Limit: 5000</pre>
<h4 id="ratelimit-remaining">RateLimit-Remaining</h4>
<p>Indique le nombre restant d'appels possibles à l'API par heure et par utilisateur.</p>
<p></p><strong>Fréquence</strong> : présent dans toutes les réponses.</p>
<pre>
HTTP/1.1 400 Bad Request
Status: 400 Bad Request
RateLimit-Remaining: 224</pre>
</div>
<div id="sidebar" class="span5"></div>
</div>
</div> <!-- /container -->
<footer>
</footer>
<script type="text/javascript">window.hijs = '.highlight';</script>
<script type="text/javascript" src="js/hijs.js"></script>
</body>
</html>