API

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

URL https://api.mon-territoire.fr/
Version déployée 0.4.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. Seuls le numéro majeur de la version est retenu.

Exemple :

  • https://api.mon-territoire.fr/v0/controls
  • https://api.mon-territoire.fr/v1/controls

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

Exemple :

  • https://api.mon-territoire.fr/controls

En-tête de requète

Le format JSON est actuellement le seul format proposé et accepté.
Lors de l'envoi de chaque requète, n'oubliez pas les en-têtes suivants :

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

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 avec création d’une nouvelle ressource.
204 No Content
Requête traitée avec succès mais aucune information n'est renvoyée.
Erreurs du client
400 Bad Request
La syntaxe de la requête est erronée, du à 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.
Voir Authentification plus bas.
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.

Authentification

La plupart des points d'API requiert une authentification.
A l'exception de quelques cas particuliers, deux ressources sont requises pour parfaire une authentification : un utilisateur et une collectivité.

La collectivité est en général automatiquement assignée et retournée lors du POST.
Dans le cas ou celle-ci serait absente (ou si vous avez accés à plusieurs collectivités et souhaitez changer), vous pouvez :

Exemples fournis

Cette documentation propose de nombreux exemples fonctionnels, construits avec httpie.
Vous pouvez reproduire ces exemples en adaptant les données envoyées (identifiants, ids, recherche, ...).
Afin de conserver votre session et votre authentification entre les requêtes, il est conseillé d'ajouter les options suivantes dans le fichier de configuration de httpie ~/.httpie/config.json.

"default_options": [
  "--session=default"
]