API SignalNids — documentation & exemples

⚡ Démarrage rapide

Base

https://signalnids.fr

Format

JSON (Content-Type: application/json; charset=utf-8)

Version

v1 (sans préfixe pour l’instant)

Exemple cURL (liste des derniers signalements publics)

curl -s https://signalnids.fr/api/reports_latest.php

Tous les endpoints renvoient {"ok": true, ...} en succès et {"ok": false, "error": "...", ...} en échec.

🔐 Authentification

Deux modes sont utilisés selon l’endpoint :

Session + CSRF (navigateur) : l’utilisateur est connecté à SignalNids ; fournir le token CSRF (champ csrf ou header X-CSRF-Token).
Bearer (script/serveur à serveur) : si vous disposez d’un jeton d’accès (optionnel). Header Authorization: Bearer <token>.

Les endpoints d’écriture (création de signalement, vote) exigent l’un ou l’autre selon votre contexte.

🧭 Endpoints (v1)

GET Derniers signalements

GET https://signalnids.fr/api/reports_latest.php?limit=20

Public – renvoie les N derniers points (ville, coords approximatives, intensité, statut).

{
  "ok": true,
  "items": [
    {"id": 123, "city": "Arras", "latitude": 50.289650, "longitude": 2.780573, "intensity": 3, "status":"a_verifier", "created_at":"2025-10-24 10:56:00"}
  ]
}

POST Créer un signalement

POST https://signalnids.fr/api/report_create.php (auth + CSRF)

Body

multipart/form-data (ou application/x-www-form-urlencoded) – champs clés : latitude, longitude, city, intensity, species, nest_location, status, comment, photos[]

curl -X POST https://signalnids.fr/api/report_create.php \
  -H "X-CSRF-Token: <csrf>" \
  -F "latitude=50.28965" -F "longitude=2.780573" -F "city=Arras" \
  -F "intensity=3" -F "species=frelon_asiatique" -F "nest_location=arbre" \
  -F "status=a_verifier" -F "comment=Nid sous la toiture" \
  -F "photos[]=@/chemin/photo1.jpg"

{"ok": true, "id": 456}

POST Voter (like/dislike)

POST https://signalnids.fr/api/report_vote.php (auth + CSRF)

Champs : report_id, value ∈ {-1, 0, 1} (0 = annuler vote). Retourne les compteurs.

curl -X POST https://signalnids.fr/api/report_vote.php \
  -H "X-CSRF-Token: <csrf>" \
  -d "report_id=456" -d "value=1"

{"ok": true, "likes": 3, "dislikes": 0, "user_vote": 1}

GET Notifications (auth)

GET https://signalnids.fr/api/notifications_list.php – renvoie les notifications non lues + récentes.

{"ok": true, "items":[
  {"id": 12, "type":"like", "actor_name":"Alice", "actor_avatar":"/uploads/avatars/a.png",
   "report_id":456, "report_city":"Arras", "link":"/report.php?id=456",
   "created_at":"2025-10-24 11:10:00", "read_at": null}
]}

POST https://signalnids.fr/api/notifications_read.php (ids=all ou liste d’identifiants) pour marquer comme lus.

📄 Pagination & tri

Les endpoints listants acceptent d’ordinaire :

?page=1 (défaut 1), ?limit=20 (max 100)
Tri le plus récent d’abord (si non précisé).

GET https://signalnids.fr/api/reports_latest.php?page=2&limit=20

🚫 Gestion des erreurs

{"ok": false, "error": "Paramètres invalides", "code": 422}

400

Requête invalide

401

Non authentifié

403

CSRF ou droits insuffisants

404

Ressource introuvable

422

Validation échouée

429

Trop de requêtes

500

Erreur serveur

🛡️ Sécurité

CSRF exigé sur POST/PUT/PATCH/DELETE en contexte session.
Uploads restreints (JPEG/PNG/WebP) et contrôlés par mimetype + taille.
Logging d’audit (IP de session, date) côté serveur.
Les points affichés publiquement sont approximatifs pour la vie privée.

⏱️ Limites & CORS

Des limites raisonnables sont appliquées (ex. 60 req/min par IP sur endpoints publics). Les origines autorisées en CORS sont restreintes à signalnids.fr par défaut.

🗒️ Versionning

L’API est pour l’instant servie en v1 sans préfixe. Les changements notables sont listés sur la page Changelog. Les ruptures feront l’objet d’un préavis et d’un préfixe (/v2/...).