Prise en main¶
Cette page suffit pour un premier appel. Les règles détaillées sont dans Authentification et permissions ; la description de chaque endpoint est sur la page de son domaine.
1. Obtenir un jeton¶
curl -X POST https://<instance>/api/auth/login/ \
-H "Content-Type: application/json" \
-d '{"email": "utilisateur@exemple.fr", "password": "…"}'
{
"access": "eyJhbGciOi…",
"refresh": "eyJhbGciOi…",
"user": { "id": 12, "email": "utilisateur@exemple.fr", "niveau_role": "utilisateur", "…": "…" }
}
Le champ email accepte indifféremment l'adresse e-mail ou l'identifiant de connexion. Sur une instance reliée à GeoNature, utiliser /api/auth/login-geonature/ ; GET /api/auth/mode/ indique le mode de connexion de l'instance.
2. Appeler l'API¶
Le jeton d'accès se transmet dans l'en-tête Authorization :
Quand il expire, l'API répond 401. Demander un nouveau jeton d'accès avec le jeton de rafraîchissement (qui est lui-même renouvelé à chaque appel) :
curl -X POST https://<instance>/api/auth/refresh/ \
-H "Content-Type: application/json" \
-d '{"refresh": "<refresh>"}'
Pagination¶
Les listes renvoient une enveloppe commune :
{
"links": { "next": "https://…/api/plans/plans/?page=2", "previous": null },
"pagination": {
"count": 44, "current_page": 1, "total_pages": 3,
"page_size": 20, "has_next": true, "has_previous": false
},
"results": [ … ]
}
| Paramètre | Rôle |
|---|---|
page |
Numéro de page (à partir de 1) |
page_size |
Taille de page, 20 par défaut, 1 000 au maximum (500 sur les exports et statistiques) |
Quelques endpoints « par parent » (…/by-plan/{id}/, …/by-enjeu/{id}/…) renvoient une liste simple, non paginée : ils servent à charger une arborescence complète.
Filtrer, chercher, trier¶
Trois mécanismes se combinent sur la plupart des listes :
| Paramètre | Exemple | Effet |
|---|---|---|
| champ | ?statut=valide&id_organisme=3 |
Filtre exact sur un champ (la liste des champs est dans Swagger) |
search |
?search=camargue |
Recherche texte sur les champs déclarés par l'endpoint |
ordering |
?ordering=-annee_debut,nom_pg |
Tri, - pour l'ordre décroissant |
Écrire¶
POSTcrée,PUTremplace,PATCHmodifie partiellement,DELETEsupprime.- Les réponses de création renvoient l'objet créé (
201), les suppressions204. - Les actions métier (valider un plan, lier un site, approuver une demande…) sont des
POSTsur des sous-chemins explicites, par exemplePOST /api/plans/plans/{id}/change-status/. - Les identifiants ont le nom de la clé primaire du modèle :
id_pgpour un plan,id_enjeu,id_operation,id_rolepour un utilisateur,slugpour un site.
Erreurs¶
Les erreurs sont en JSON et portent l'identifiant de corrélation à citer dans un signalement :
Les erreurs de validation (400) détaillent les champs en cause :
{ "nom_pg": ["Ce champ est obligatoire."], "annee_fin": ["Doit être postérieure à annee_debut."], "correlation_id": "7f0c…" }
| Code | Signification |
|---|---|
400 |
Requête invalide (le corps détaille les erreurs par champ) |
401 |
Jeton absent, invalide ou expiré |
403 |
Droits insuffisants, ou plan verrouillé (hors brouillon) |
404 |
Ressource inexistante, ou hors du périmètre de l'utilisateur (l'API ne distingue pas les deux cas) |
409 |
Conflit métier (par exemple un brouillon enfant existe déjà) |
502 |
Exploration nationale : hub injoignable, aucun repli sur l'index local |
500 |
Erreur interne, journalisée côté serveur avec le même correlation_id |
Géométries¶
Les géométries de sites, de plans, d'enjeux et d'actions sont lues et écrites en GeoJSON (WGS 84). Les endpoints …/geojson/ et …/geojson_list/ renvoient directement une Feature ou une FeatureCollection exploitable dans un SIG.