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.

Endpoint 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 :

http://URL:port/swagger/

Voir la documentation Swagger{ .md-button .md-button--primary }

Aussi accessible via le bouton sur la page d'administration

Documentation de l'API

Qu'est-ce qu'une API ?

Qu'est-ce que Swagger ?

Endpoint pour les mailings listes

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

GET /api/emails/

GET /api/emails/<id>/