Lister et rechercher des utilisateurs

La liste des utilisateurs et la recherche des utilisateurs se fait avec un même WebService accessible à l'adresse /api/users/ via la méthode HTTP GET.

Paramètres

Nom	Sémantique	Valeurs permises	Exemple
ordering	Permet de passer le nom d'un champ par lequel les réponses seront ordonnées, préfixé par - l'ordre est inversé	[-]date_joined, [-]modified, [-]first_name, [-]last_name
first_name	recherche exacte sur le prénom pour une valeur exacte
first_name__iexact	recherche exacte sur le prénom pour une valeur exacte en ignorant la casse
first_name__icontains	recherche exacte sur le prénom pour une sous chaîne en ignorant la casse
first_name__gte	recherche sur le prénom supérieure ou égale à la valeur
first_name__lte	recherche sur le prénom inférieure ou égale à la valeur
first_name__gt	recherche sur le prénom supérieure à la valeur
first_name__lt	recherche sur le prénom inférieure à la valeur
last_name + __iexact, __icontains, __gte, __lte, __gt, __lt	idem que pour le prénom mais avec le nom
modified__gte	recherche sur la date de dernière modification supérieure ou égale à la valeur	date et heure au format ISO-8601: YYYY-MM-DDTHH:MM:SS	curl -X GET -u login:password https://authentic/api/users/?modified__gte=2017-03-28T00:00:00
modified__lte	recherche sur la date de dernière modification inférieure ou égale à la valeur	date et heure au format ISO-8601: YYYY-MM-DDTHH:MM:SS
modified__gt	recherche sur la date de dernière modification supérieure à la valeur	date et heure au format ISO-8601: YYYY-MM-DDTHH:MM:SS
modified__lt	recherche sur la date de dernière modification inférieure à la valeur	date et heure au format ISO-8601: YYYY-MM-DDTHH:MM:SS
email	recherche sur le courriel exact
email__iexact	recherche sur le courriel exact en ignorant la casse
ou__slug	recherche dans une unité organisationnelle	identifiant court (slug) de l'unité organisationnelle
service-slug & service-ou	recherche des utilisateurs autorisés pour un service	service-slug prend pour valeur l'identifiant court (slug) du service et service-ou prend pour valeur l'identifiant court (slug) de l'unité organisationnelle dans laquelle est le service (« default » si le service est dans l'unité par défaut)

Format de retour

Le document retour est un objet/dictionnaire JSON, les résultats sont toujours paginés, chaque page a une taille de 100, le lien vers la page suivante est dans la propriété next et celui vers la page précédente dans la propriété previous. La propriété results contient la liste des résultats.

La liste des attributs dépend des attributs configurés dans le profil d'un utilisateur. Les attributs sont au minimum les suivant :

Propriété	Description	Format
uuid/sub	identifiant/identifiant OIDC de l'utilisateur	chaîne hexadécimal
first_name	prénom	chaîne quelconque
last_name	nom	chaîne quelconque
email	adresse de courriel	adresse de courriel
email_verified	statut de validation de l'adresse de courriel	true/false
modified	date de dernière modification	date et heure au format ISO-8601: YYYY-MM-DDTHH:MM:SS
date_joined	date de création	date et heure au format ISO-8601: YYYY-MM-DDTHH:MM:SS
is_active	statut d'activation du compte	true/false

Exemple

GET /api/users/ HTTP/1.1
Authorization: Basic xxx

200 Ok
Content-Type: application/json
Content-Length: xxxx

{
    "next": "https://cresson.entrouvert.org/api/users/?cursor=XYZ",
    "previous": null,
    "results": [
        {
            "date_joined": "2017-07-25T08:41:40.998793Z",
            "email": "bob.leponge@france.fr",
            "email_verified": true,
            "first_name": "Bob",
            "is_active": true,
            "last_name": "Léponge",
            "modified": "2017-08-31T15:16:29.690864Z",
            "sub": "YTIBAQB9-fZcwZKt7k28P_towGlszsW0uDvxq5hd_zQOJhGBJ1qP3FYajF-JUY6ug_Ekw8k",
        },
        ...
    ]
}

Cas non-passant

Code	Signification	Contenu
400	Le format de la requête est invalide (paramètre interdit ou avec une valeur invalide)	Un document JSON décrivant les erreurs rencontrées
401	L'authentification a échouée
403	Permission non accordée d'effectuer l'action

Pagination des résultats

La réponse d'un cas passant contient au maximum 100 utilisateurs. Si le resultat est supérieur à 100 utilisateurs, le résultat se découpe en plusieurs pages et la réponse à la requête initiale ne contient que les 100 premiers utilisateurs de la liste. Il faut ensuite parcourir les pages suivantes en interrogeant l'url spécifiée dans le champs next de la réponse et cela jusqu'à ce que le champs next soit à null.

Par exemple :

GET /api/users/ HTTP/1.1
Authorization: Basic xxx

200 Ok
Content-Type: application/json
Content-Length: xxxx

{
    "next": "https://moncompte.grandlyon.com/api/users/?cursor=XYZ",
    "previous": null,
    "results": [
        {
...

Le champs next indique qu'il y a une autre page de résultat que l'on obtient par la requête :

GET /api/users/?cursor=XYZ HTTP/1.1
Authorization: Basic xxx

200 Ok
Content-Type: application/json
Content-Length: xxxx

{
    "next": null,
    "previous": "https://moncompte.grandlyon.com/api/users/?cursor=ABC",
    "results": [
        {
...

Filtrage selon un rôle

Pour limiter les résultats aux utilisateurs disposant d’un rôle, il faut utiliser l’API permettant de lister les membres d'un rôle, elle expose les mêmes paramètres et le même fonctionnement que l’API décrite sur cette page.

Documentation en ligne