Documentation de l'API

Librairies utilisées:

Django rest framework pour l'implémentation de class générique, ce qui permet une meilleure maintenabilité.
drf-yasg pour l'ajout d'une interface de documentation automatisée de l'API

Qu'est-ce qu'une API ?

Une API (Application Programming Interface) est une application qui permet d'acceder à des données de manière standard.
Ce qui permet la communication entre differentes application ou l'automatisation de certaines fonctionnalités Dans le cadre du web, une API REST fournit des points d'accès (ou endpoints) aux données d'un système via le protocole HTTP.

Exemples d'opérations REST :

GET : récupérer des données
POST : créer de nouvelles données
PUT / PATCH : mettre à jour des données
DELETE : supprimer des données

Les API permettent par exemple à une interface web ou à une application mobile de dialoguer avec un serveur distant.

L'API de MyGDR n'implémente que les fonctionnalités utiles pour limiter la surface d'attaque potentielle et la dégradation des données.

Qu'est-ce que Swagger ?

Swagger est un outil qui permet de documenter et tester facilement les API REST. Il repose sur la spécification OpenAPI. Grâce à Swagger :

Chaque point d'accès de l'API est clairement documenté (paramètres, méthodes, réponses, etc.)
Un utilisateur peut interagir avec l'API directement depuis une interface web
L’API devient auto-descriptive et facile à maintenir
L'interface de swagger n'est disponible qu'aux utilisateurs disponsant des droits administrateurs pour le moment.

Permissions API – Accès GT / GDR

Permission `IsAllowedOnGTOrGDR`

Cette permission contrôle l’accès aux données en fonction des GT et GDR autorisés pour chaque utilisateur via son profil API.

Règles d’autorisation

Un utilisateur est autorisé à accéder à une ressource si au moins une des conditions suivantes est vraie :

L’utilisateur est administrateur (user.is_staff = True)
Le paramètre gt_acro est présent dans l’URL ET fait partie de ses GT autorisés
Le paramètre gdr_acro est présent dans l’URL ET fait partie de ses GDR autorisés

Les GT d’un GDR autorisé sont automatiquement accessibles.

Profil API requis

Chaque utilisateur non admin doit posséder un profil API (APIUserProfile) contenant :

allowed_gts : liste des GT autorisés
allowed_gdrs : liste des GDR autorisés

Sans ce profil, tout accès est refusé.

Fonctionnement détaillé

Vérification globale (`has_permission`)

Cas	Accès
Utilisateur non authentifié	❌ Refusé
Administrateur (`is_staff`)	✅ Autorisé
Pas de profil API	❌ Refusé
`gt_acro` autorisé (`profil API`)	✅ Autorisé
`gdr_acro` autorisé (`profil API`)	✅ Autorisé

Exemple avec point d'acces (URL) pour les mailings listes

Point d'acces (ou endpoint) : `/api/emails/`

`GET /api/emails/`

Retourne la liste des utilisateurs avec leur email, prénom et nom. Deux filtres sont disponibles :

gdr_acro : pour filtrer selon l'acronyme d'un GDR
gt_acro : pour filtrer selon l'acronyme d'un GT

Paramètres :

Nom	Type	Description
gdr_acro	string	Acronyme du GDR à filtrer
gt_acro	string	Acronyme du GT à filtrer

Réponse disponible en JSON ou CSV :

[
  {
    "email": "jean.dupont@example.com",
    "first_name": "Jean",
    "last_name": "Dupont"
  }
]

`GET /api/emails/<id>/`

Retourne les informations d'un utilisateur spécifique.

Réponse disponible en JSON ou CSV

{
  "email": "jean.dupont@example.com",
  "first_name": "Jean",
  "last_name": "Dupont"
}

Endpoints villes

Point d'acces (ou endpoint) : `/api/villes/`

`GET /api/villes/`

Retourne la liste des villes en base, au format CSV ou JSON selon le type de réponse demandé (via l'en-tête Accept).

Réponse JSON:

[
  {
    "ville": "Paris",
    "longitude": 2.352221,
    "latitude": 48.856614
  }
]

Réponse CSV :

ville,longitude,latitude
Paris,2.352221,48.856614

`POST /api/villes/`

Permet d'importer un fichier CSV contenant des villes avec leurs coordonnées.

Format attendu du fichier CSV:

ville,latitude,longitude
Paris,48.856614,2.352221

Réponse JSON :

{
  "message": "4 villes importées ou mises à jour avec succès."
}

Codes de retour :

201 : succès de l'importation
400 : erreur de fichier ou de données

Authentification

Toutes les routes de l’API sont protégées par Basic Auth : il faut fournir un identifiant/mot de passe valide pour y accéder.

Format des données

Les Point d'acces (ou endpoint)s /api/emails/ et /api/villes/ supportent les formats JSON et CSV (en lecture uniquement pour ce dernier). Vous pouvez choisir le format via le sélecteur "Response content type" dans Swagger, ou l'en-tête Accept dans vos requêtes HTTP.

Exemple d'utilisation via `curl`

Lister les villes :

curl -u user:pass -H "Accept: text/csv" http://URL:port/api/villes/

Pour plus d'informations, consultez la documentation interactive générée par Swagger à l'adresse :

https://mygdr.hosted.lip6.fr/swagger/

Voir la documentation Swagger

Aussi accessible via le bouton sur la page d'administration