Skip to content

Documentation pour la mise à jour des listes sympa via l'API de MyGDR

Objectifs :

Cette documentation décrit comment utiliser l'API REST de l'application MyGDR pour alimenter dynamiquement des listes de diffusion Sympa via son interface web. L'objectif est de simplifier et d'automatiser la mise à jour des listes Sympa à partir des GTs et GDRs.

Pré-requis

Avant de configurer Sympa pour interroger l'API, assurez-vous d'avoir :

  • Être propriétaire de sa liste Sympa et avoir la permission d'accès à l'API via un compte administrateur ou un profil API.
  • Les identifiants d'accès API (username / mot de passe) sont les mêmes que pour le compte administrateur de MyGDR ou du profil API.
  • L'URL du point d'acces à l'API (disponible sur l'interface de documentation de l'API https://mygdr.hosted.lip6.fr/swagger/).

Fonctionnement de l'API

L'API expose un endpoint (point d'accès) dédié permettant de :

  • Lister les utilisateurs avec leur email, prénom et nom.
  • Filtrer les utilisateurs selon plusieurs critères.
  • Récupérer un utilisateur unique.

Endpoints disponibles

1. Lister tous les utilisateurs

GET /api/users/emails/
````

#### Filtres disponibles

| Paramètre          | Type    | Description                                                                 |
| ------------------ | ------- | --------------------------------------------------------------------------- |
| `gdr_acro`         | string  | Filtrer par acronyme du GDR                                                 |
| `gt_acro`          | string  | Filtrer par acronyme du GT                                                  |
| `genre`            | string  | Filtrer par genre (`Femme`, `Homme`, `Non binaire`)                         |
| `date_prise_poste` | integer | Filtrer par année de prise de poste                                         |
| `sans_gt`          | boolean | Filtrer uniquement les utilisateurs sans GT et sans statut (`true`/`false`) |

#### Formats de réponse disponibles

| Format           | Usage                                                             | Paramètre ou Header                   |
| ---------------- | ----------------------------------------------------------------- | ------------------------------------- |
| TXT (plain text) | Format par défaut compatible Sympa (une adresse e-mail par ligne) | `?format=txt` ou `Accept: text/plain` |
| JSON             | Format pour tests/debug (email + prénom + nom)                    | `Accept: application/json`            |
| CSV              | Export CSV des utilisateurs (email, prénom, nom)                  | `?format=csv`                         |


##### Exemple: 
````https
https://mygdr.hosted.lip6.fr/api/emails/?gt_acro=ACE
````

---

### 2. Récupérer un utilisateur spécifique

```http
GET /api/users/emails/{id}/
  • Réponse :

json { "email": "alice@example.com", "first_name": "Alice", "last_name": "Durand" }

Réponse attendue (plain text, format par défaut, pour Sympa):

alice@example.com
bob@example.com
charlie@example.org
...

Authentification

L'API est sécurisée par authentification HTTP Basic.

  • L'identifiant (username) et le mot de passe (password) doivent être fournis dans la configuration de Sympa.

Configuration dans l'interface web de Sympa

1. Se connecter à l’interface d’administration de la liste

Accédez à votre site Sympa via l’interface web avec les droits de gestion sur la liste cible.

2. Aller dans "Configurer la liste" > "Définition des sources de données"

  • Catégorie : Inclusion d'un fichier distant
  • Voici les champs à remplir pour une source distante :
Champ Description
Nom court pour cette source Identifiant sympa de cette source d’abonnement.
URL des données ex: /api/users/emails/?gt_acro=Acronyme_du_GT&format=txt
Utilisateur Identifiant d'accès, nom utilisateur MyGDR.
Mot de passe de la source Mot de passe associé.
Délai d'inactivité Durée maximale avant rechargement des données (exemple : 1d pour 1 jour).

3. Valider

  • Sauvegardez la configuration.
  • Allez dans la gestion des abonnés pour vérifier que la liste est automatiquement alimentée.

Debug et tests

Vous pouvez tester l’API sur l'interface dédiée si vous avez accès à la page d'administration de MyGDR :

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

En cas de problème :

  • Vérifiez les droits de l’utilisateur API.
  • Vérifiez la réponse de l’API.
  • Vérifiez que le format txt est bien utilisé par défaut (requis par Sympa).

Comment donner les droits droits d'accès à un membre du CNRS

1. Créer un utilisateur.

  • Aller dans la page d'administration.
  • Aller dans la catégorie utilisateur et créer un compte avec nom d'utilisateur, mot de passe, nom et prénom.

2. Donner les droits d'acces à la route API du GT.

  • Dans la page d'administration, aller dans Profils API.
  • Ajouter un profil API.
  • Choisir un utilisateur (User).
  • Donner les droits pour un GT.

### /!\ Attention /!\ - Les utilisateurs ainsi créés accepetent les conditions d'utilisation (CGU) de façon automatique. - Si l'utilisateur profil API a déjà un compte MyGDR, il n'est pas necessaire de créé un nouveau compte. Il suffit de l'associer à un GDR ou à un GT pour lui donner les droits d'accès. - Les utilisateurs RespGDR et RespGT n'ont pas besoin d'un profil API étant donné qu'ils ont un statut équipe (administrateur).