Documentation de l'API Ecodrop

Ce document fournit la documentation de l'API REST pour le projet Ecodrop.

Tester l'API

L'API Ecodrop est accessible via deux domaines différents pointant vers le même serveur :

• https://ecodrop.edihamiti.fr/docs
• https://ecodrop.jonas-facon.dev/docs

Liste des administrateurs

Afin de tester les fonctionnalités réservées aux administrateurs, il est nécessaire de se connecter via GitLab en utilisant l'une des adresses e-mail suivantes :

• philippe.mathieu@univ-lille.fr
• jonas.facon.etu@univ-lille.fr
• edi.hamiti.etu@univ-lille.fr

Authentification

Le projet utilise un système d'authentification déléguée basé sur le protocole OAuth2. Nous ne stockons pas de mots de passe ; l'identité des utilisateurs est vérifiée par des fournisseurs de confiance (GitLab, Discord, Google, GitHub).

Fonctionnement du flux

1. Sélection du fournisseur : L'utilisateur choisit un service (ex: GitLab) sur la page d'accueil.
2. Autorisation externe : L'utilisateur est redirigé vers le site du fournisseur pour autoriser Ecodrop à accéder à ses informations de profil (email, pseudo).
3. Échange du code : Le fournisseur redirige l'utilisateur vers notre API (/auth/token) avec un Authorization Code.
4. Récupération de l'identité : L'API échange ce code contre un Access Token, puis récupère les informations de l'utilisateur.
5. Persistance et Rôle : L'API vérifie si l'utilisateur existe en base de données. S'il s'agit d'une première connexion, un compte est créé. Le rôle (USER ou ADMIN) est récupéré.
6. Génération du JWT : L'API génère un jeton JWT (JSON Web Token) signé, contenant l'ID, l'email et le rôle de l'utilisateur. Ce jeton doit être envoyé par le client dans le header Authorization: Bearer <token> pour chaque requête protégée.

sequenceDiagram
    participant Client
    participant API as API Ecodrop
    participant DB as Base de données
    participant Provider as OAuth Provider

    Client->>Provider: 1. Demande d'autorisation (Login)
    Provider-->>Client: 2. Redirection vers callback avec Code
    Client->>API: 3. Appel /auth/token?code=...
    API->>Provider: 4. Échange Code contre Access Token
    Provider-->>API: 5. Retourne Access Token
    API->>Provider: 6. Demande infos utilisateur (email, pseudo)
    Provider-->>API: 7. Retourne infos utilisateur
    API->>DB: 8. Vérifie/Crée l'utilisateur & récupère son rôle
    DB-->>API: 9. Utilisateur (id, role)
    API-->>Client: 10. Retourne JWT interne signé

Loading

Autorisations et Rôles

Le SecurityFilter de l'API applique les règles suivantes :

Méthode	Endpoint	Accès
GET	(tous sauf exception)	Public
GET	/points/overloaded	ADMIN
POST	/deposits	USER / ADMIN
DELETE	(tous)	ADMIN
POST, PUT, PATCH	(autres)	ADMIN

Limitation de débit (Rate Limiting)

Pour garantir la stabilité du service, une limitation de débit est appliquée sur l'ensemble des endpoints de l'API :

• Limite : 100 requêtes par minute et par adresse IP.
• Dépassement : En cas de dépassement de cette limite, l'API renvoie un code d'erreur 429 Too Many Requests.

Pagination

Les endpoints listant plusieurs ressources (points de collecte, dépôts, utilisateurs, etc.) supportent la pagination via deux paramètres de requête optionnels :

• limit : Nombre maximum de résultats à retourner.
  • Valeur par défaut : 20
• offset : Nombre de résultats à sauter avant de commencer à retourner les données.
  • Valeur par défaut : 0

Exemple d'utilisation : /ecodrop/users/leaderboard?limit=5&offset=10

Formats de données

L'API supporte les formats JSON (par défaut) et XML pour les échanges de données.

• Pour l'envoi de données (POST, PUT, PATCH) : Spécifiez le format dans le header Content-Type (ex: application/json ou application/xml).
• Pour la réception de données (GET) : Spécifiez le format souhaité dans le header Accept (ex: application/json ou application/xml).

Endpoints disponibles

• Authentification (Token)
• Utilisateurs
• Types de déchets
• Points de Collecte
• Dépôts
• Base de données

Documentation alternative (Format Philippe Mathieu)

• Authentification (Token)
• Utilisateurs
• Types de déchets
• Points de Collecte
• Dépôts

Base de données

Le schéma suivant représente l'organisation des données dans l'application.

classDiagram
direction BT

class Users {
   int id PK
   string login
   string role
}

class WasteType {
   int id PK
   string nom
   int pointsPerKilo
}

class CollectionPoint {
   int id PK
   string adresse
   int capaciteMax
}

class Accepts {
   int pointid FK
   int wastetypeid FK
}

class Deposit {
   int id PK
   int userid FK
   int pointid FK
   int wastetypeid FK
   int poids
   datetime dateDepot
   boolean collected
}

CollectionPoint "1" --> "0..*" Deposit : pointid
Users "1" --> "0..*" Deposit : userid
WasteType "1" --> "0..*" Deposit : wastetypeid

CollectionPoint "1" --> "0..*" Accepts : pointid
WasteType "1" --> "0..*" Accepts : wastetypeid

Loading

Requêtes Complexes

Classement des utilisateurs par points

Récupère les utilisateurs et leur nombre total de points par ordre décroissant.

SELECT Users.login, SUM(Deposit.poids * WasteType.pointsPerKilo) AS totalPoints
FROM Users
JOIN Deposit ON Users.id = Deposit.userId
JOIN WasteType ON Deposit.wasteTypeId = WasteType.id
GROUP BY Users.id, Users.login
ORDER BY totalPoints DESC
LIMIT ? OFFSET ?

Capacité actuelle d'un point de collecte

Récupère la capacité maximale et le poids total actuel des dépôts non collectés pour un point donné.

SELECT cp.capaciteMax, COALESCE(SUM(d.poids), 0) AS totalWeight
FROM CollectionPoint cp 
LEFT JOIN Deposit d ON d.pointid = cp.id AND d.collected IS FALSE
WHERE cp.id = ? 
GROUP BY cp.id, cp.capaciteMax

Points de collecte surchargés (> 80%)

Identifie les points de collecte dont le taux de remplissage dépasse 80% de leur capacité maximale.

SELECT cp.id, cp.adresse, cp.capaciteMax, COALESCE(SUM(d.poids), 0) AS totalPoids 
FROM CollectionPoint cp 
LEFT JOIN Deposit d ON d.pointid = cp.id AND d.collected IS FALSE
GROUP BY cp.id, cp.adresse, cp.capaciteMax 
HAVING cp.capaciteMax > 0 AND (COALESCE(SUM(d.poids), 0) * 100.0 / cp.capaciteMax) > 80