A propos de l'API

Cette documentation a pour but de décrire l'API REST de l'Atelier Serveur.
Cette API vous donne accès aux données de votre collectivité en JSON.


Version de l'API

Version déployée 0.5.0

Le versionnage de l'API utilise le format major.minor.micro. (cf wikipedia).
L'API est versionnée grâce à l'usage d'un préfix dans l'URL. Seul le numéro majeur de la version est retenu.

Ce préfix peut être omis lorsque vous communiquez avec la dernière version déployée.

Exemple :

https://api.mon-territoire.fr/v0/search
https://api.mon-territoire.fr/v1/search
https://api.mon-territoire.fr/search

Format de requête

Sauf mentions contraires, le format JSON est le format attendu et retourné par défaut.
Lors de l'envoi de chaque requête, n'oubliez pas les en-têtes suivants :

Content-Type: application/json
Accept: application/json

Certaines ressources acceptent d'autres formats comme le PDF ou le CSV.
Dans ce cas, vous pouvez demander une autre représentation de la ressource en utilisant l'en-tête approprié ou en ajoutant l'extension adéquate à la fin de l'URL.

Liste des formats possibles :

JSON Accept: application/json .json
GeoJSON Accept: application/json ou Accept: application/geo+json .json ou .geojson
PDF Accept: application/pdf .pdf
CSV Accept: text/csv .csv

Code HTTP

Vous pouvez déterminer le résultat de chaque requête en vérifiant le code HTTP de sa réponse.
Ces codes sont standards et bien documentés sur wikipedia, mais vous trouverez ci-dessous une liste des codes récurrents.

Succès
200 OK
Requête traitée avec succès
201 Created
Requête traitée avec succès. Une ressource a été créée.
204 No Content
Requête traitée avec succès. Aucun contenu n'est renvoyé.
Erreurs du client
400 Bad Request
La syntaxe de la requête est erronée, dû à une erreur lors de l'envoi.
Le cas le plus fréquent est l'oubli d'un paramètre requis. Consultez la documentation du point d'API correspondant pour plus de détails.
401 Unauthorized
Une authentification est nécessaire pour accéder à la ressource.
Consultez la section Authentification pour plus de détails.
403 Forbidden
Vous ne disposez pas d'un droit d'accès suffisant pour cette ressource.
404 Not Found
Cette ressource n'a pas été trouvée ou n'est plus disponible.
422 Unprocessable
La requête est correcte mais a été rejetée.
Le cas le plus fréquent est l'absence de propriétés requises lors de l'enregistrement d'une ressource.
Dans ce cas, le corps de la réponse peut vous fournir quelques détails.

Exemples fournis et HTTPie

Cette documentation propose de nombreux exemples fonctionnels, construits avec HTTPie.
Vous pouvez ainsi reproduire ces exemples, en adaptant bien sur les paramètres envoyés (token, identifiants, critères de recherche, etc).