API Backend — Conventions & Authentification¶

Vue d'ensemble¶

L'API backend de DAREWATCH est une API REST qui alimente les trois services frontends. Elle suit les conventions JSON standard et utilise JWT pour l'authentification.

graph TD
    T[drwh_tech] -->|HTTP REST| API[API Backend]
    I[drwh_immo] -->|HTTP REST| API
    G[drwh_group] -->|HTTP REST| API
    A[drwh_admin] -->|HTTP REST\nJWT Auth| API
    API --> DB[(Base de données)]

    style API fill:#8e44ad,color:#fff
    style DB fill:#f39c12,color:#fff
    style A fill:#e74c3c,color:#fff

URLs de base¶

Environnement	URL de base
Production	`https://api.darewatch.com/api/v1`
Staging	`https://api-staging.darewatch.com/api/v1`
Développement	`http://localhost:3000/api`

En-têtes requis¶

Content-Type: application/json
Authorization: Bearer <JWT_TOKEN>    ← Requis pour toutes les routes /admin/*

Format de réponse standard¶

Succès — ressource unique

json { "success": true, "data": { "id": 1, "title": "Service Web", "created_at": "2026-04-01T10:00:00Z" } }

Succès — liste paginée

json { "success": true, "data": [...], "meta": { "total": 42, "page": 1, "pageSize": 10, "lastPage": 5 } }

Erreur

json { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Le champ email est requis.", "details": { "email": ["Le champ email est requis."] } } }

Codes de réponse HTTP¶

Code	Signification	Usage
`200 OK`	Succès	GET, PUT (mise à jour)
`201 Created`	Ressource créée	POST (création)
`204 No Content`	Suppression réussie	DELETE
`400 Bad Request`	Données invalides	Erreur de validation
`401 Unauthorized`	Non authentifié	Token manquant ou expiré
`403 Forbidden`	Non autorisé	Permissions insuffisantes
`404 Not Found`	Ressource introuvable	ID inexistant
`422 Unprocessable`	Erreur de validation	Données mal formatées
`500 Server Error`	Erreur serveur	Bug côté backend

Authentification JWT¶

sequenceDiagram
    participant C as Client (Admin)
    participant A as API Backend

    C->>A: POST /auth/login\n{ email, password }
    A-->>C: 200 { token, user }

    Note over C: Stocke le token JWT

    C->>A: GET /admin/services\nAuthorization: Bearer <token>
    A-->>C: 200 { data: [...] }

    Note over C,A: Token expiré après 24h

    C->>A: POST /auth/refresh\n{ refresh_token }
    A-->>C: 200 { token, refresh_token }

POST /auth/login
Content-Type: application/json

{
  "email": "admin@darewatch.com",
  "password": "motdepasse"
}

Réponse :

{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refresh_token": "...",
    "expires_in": 86400,
    "user": {
      "id": 1,
      "email": "admin@darewatch.com",
      "role": "super_admin"
    }
  }
}

Matrice des permissions¶

Route	Public	Admin Tech	Admin Immo	Super Admin
`GET /services`	✅	✅	✅	✅
`POST /admin/services`	❌	✅	❌	✅
`GET /properties`	✅	✅	✅	✅
`POST /admin/properties`	❌	❌	✅	✅
`DELETE /admin/*`	❌	❌	❌	✅

Pagination standard¶

Toutes les routes de liste acceptent ces paramètres de requête :

GET /blog/articles?page=1&pageSize=10&sort=created_at&order=desc

Paramètre	Type	Défaut	Description
`page`	integer	1	Numéro de page
`pageSize`	integer	10	Nombre d'éléments par page
`sort`	string	`created_at`	Champ de tri
`order`	string	`desc`	Ordre : `asc` ou `desc`