RESTful API (V2)

Introduction

L’API GLPI est une API RESTful. Cette version de l’API est appelée « API de haut niveau ». L’API originale est désormais appelée « l’API héritée », mais elle est toujours disponible et, dans certains cas, permet plus de fonctionnalités au détriment de la convivialité.

Authentification

L’authentification de l’API se fait entièrement via OAuth2. Les types de subventions OAuth2 suivants sont pris en charge :

• Mot de passe : Authentifier avec un identifiant client, un secret et un nom d’utilisateur/mot de passe. C’est la méthode recommandée pour les scripts automatisés.

• Code d’autorisation : Authentification interactive. C’est la méthode recommandée pour les applications orientées utilisateur.

Les subventions qui ne nécessitent pas d’identifiants utilisateurs spécifiques ne sont actuellement pas prises en charge car aucun système virtuel utilisateur et portée n’est mis en place à ce jour.

Configuration du client

Les clients doivent être enregistrés auprès du serveur GLPI avant de pouvoir être utilisés pour s’authentifier. Les clients servent à identifier l’application/l’utilisateur qui utilise l’API et peuvent être limités à des types de subventions spécifiques.

Pour enregistrer un client, vous pouvez le faire depuis la configuration > les clients OAuth. Lorsque le client est créé, un identifiant client et un secret seront générés automatiquement.

Champs d’action

• email: Accès à l’adresse e-mail par défaut de l’utilisateur

• user: Accès aux informations de l’utilisateur

• status: Accès aux points de terminaison d’état (Ne s’applique pas lorsqu’il est accédé via les commandes CLI)

• inventory: Accès à la soumission d’inventaire depuis l’agent GLPI via l’octroi de Client Credentials

• graphql: Accès au point de terminaison GraphQL

• api: Accès à l’API (Tous les autres points de terminaison ne sont pas gérés par leur propre périmètre)

Attribution de mot de passe

Pour s’authentifier avec l’attribution du mot de passe, vous devrez effectuer une requête POST au point de terminaison /api.php/token avec les paramètres suivants dans le corps de la requête :

• grant_type: password

• client_id: L’identifiant client du client que vous utilisez

• client_secret: Le secret client du client que vous utilisez

• username: Le nom d’utilisateur de l’utilisateur sous lequel vous vous authentifiez

• password: Le mot de passe de l’utilisateur que vous êtes en train d’authentifier

• scope: La portée de la demande. Le client doit être autorisé à utiliser le périmètre demandé.

Le point d’extrémité répondra (s’il réussit) avec un objet JSON contenant les champs suivants :

• token_type: Bearer

• expires_in: Le nombre de secondes avant l’expiration du jeton. Par défaut, cette durée est réglée à 1 heure, mais elle peut être contrôlée en définissant le dans votre fichier (voir la documentation d’installation pour plus d’informations sur la configuration des constantes de configuration GLPI).GLPI_OAUTH_ACCESS_TOKEN_EXPIRESconfig/local_define.php

• access_token: Le jeton d’accès pouvant être utilisé pour authentifier les requêtes futures.

Pour les requêtes API, vous devez inclure le jeton d’accès dans l’en-tête Authorization de la requête avec le préfixe Bearer dans le format Authorization: Bearer <access_token>

Octroi de code d’autorisation

Pour s’authentifier avec la licence de code d’autorisation, vous devrez effectuer une requête GET au terminaison /api.php/authorize avec les paramètres suivants dans la chaîne de requête :

• response_type: code

• client_id: L’identifiant client du client que vous utilisez

• scope: La portée de la demande. Le client doit être autorisé à utiliser le périmètre demandé.

Le point de terminaison répondra par une redirection vers la page de connexion GLPI. Si cela réussit, l’utilisateur sera redirigé vers le client avec un paramètre dans la chaîne de requête. Ce code peut être utilisé pour obtenir un jeton d’accès en effectuant une requête POST au point de terminaison avec les paramètres suivants dans le corps de la requête :code/api.php/token

• grant_type: authorization_code

• client_id: L’identifiant client du client que vous utilisez

• client_secret: Le secret client du client que vous utilisez

• code: Le code retourné par le point de terminaison /api.php/authorize

Le point d’extrémité répondra (s’il réussit) avec un objet JSON contenant les champs suivants :

• token_type: Bearer

• expires_in: Le nombre de secondes avant l’expiration du jeton. Par défaut, cette durée est réglée à 1 heure, mais elle peut être contrôlée en définissant GLPI_OAUTH_ACCESS_TOKEN_EXPIRES dans votre fichier config/local_define.php (voir la documentation d’installation pour plus d’informations sur la configuration des constantes de configuration GLPI).

• access_token: Le jeton d’accès pouvant être utilisé pour authentifier les requêtes futures.

• refresh_token: Le jeton de rafraîchissement qui peut être utilisé pour obtenir un nouveau jeton d’accès lorsque celui actuel expire.

Attribution des Accréditations Client

L’authentification avec la concession des identifiants clients n’est prise en charge que pour le périmètre inventory. L’accès à d’autres ressources API nécessite qu’un utilisateur réel soit authentifié, ce qui n’est pas possible avec la concession des identifiants client.

Filtrage RSQL

GLPI prend en charge le filtrage « REST Query Language » (RSQL) dans un paramètre de filtre pour certains points de terminaison qui renvoient des collections d'éléments. RSQL est un sur-ensemble du « Feed Item Query Language » (FIQL). Il offre une syntaxe intuitive et facile à utiliser pour filtrer des collections d'éléments.

La syntaxe de base est la suivante : <champ><opérateur><valeur>. Pour certains opérateurs, il n'y a pas de valeur, la syntaxe est donc simplement <champ><opérateur>.

Opérateurs

Opérateur	Description	Exemple
==	Égal à	name==John
!=	Pas égal à	name!=John
=in=	Dans	name=in=(John,Paul)
=out=	Pas dans	name=out=(John,Paul)
=lt=	Moins que	age=lt=18
=le=	Inférieur ou égal à	age=le=18
=gt=	Plus grand que	age=gt=18
=ge=	Supérieur ou égal à	age=ge=18
=like=	Comme	name=like=John
=ilike=	Insensible à la casse comme	name=ilike=John
=isnull=	Est nul	name=isnull=
=isnotnull=	N’est pas nul	name=isnotnull=
=empty=	Est vide	name=empty=
=notempty=	Il n’est pas vide	name=notempty=

Les champs disponibles pour le filtrage dépendent du point de terminaison. Tout ce qui est retourné par le point de terminaison peut être filtré dans exactement le même format que celui renvoyé par le serveur. Par exemple, si un point de terminaison retourne une collection d’éléments et que chaque élément possède une propriété emails avec un tableau d’adresses e-mail contenant chacune une propriété email, vous pouvez filtrer en utilisant le nom emails.email du champ dans le filtre

Points d’extrémité

Pour obtenir la documentation spécifique à chaque point de terminaison, consultez la documentation Swagger à l'adresse /api.php/doc. Vous pouvez également envoyer une requête à /api.php/doc pour obtenir le document JSON Swagger brut si vous définissez l'en-tête Content-Type sur application/json ou ajoutez .json à la fin de l'URL.

GraphQL

L’API GLPI est également disponible via un wrapper GraphQL à /api.php/GraphQL. Comme toutes les implémentations GraphQL conformes, il est auto-documenté et n’accepte que les requêtes POST. Puisqu’il s’agit d’un enveloppement autour de l’API REST, cela signifie que tout schéma d’objets défini et disponible via l’API REST est également disponible via GraphQL. Cela signifie aussi que l’authentification est exactement la même que le reste de l’API. La seule différence est que vous pouvez accéder à plus de propriétés dans certains cas via l’API GraphQL. Par exemple, lorsque vous demandez une liste de modèles de cartouche (CartridgeItem) via l’API REST, cela retourne les ,id, name, and comment , et les propriétés des modèles d’imprimante associés. Lorsque vous demandez les données des modèles de cartouche via GraphQL, cela débloque l’accès à toutes les propriétés du schéma PrinterModal. Cela peut réduire le nombre de requêtes à faire à l’API dans certains cas.

L’implémentation du GraphQL n’inclut aucun mutateur. C’est en lecture seule.

L’API GraphQL prend en charge les mêmes paramètres que l’API REST pour le filtrage, le tri et la pagination.

Exemple de base :

query {
    Ticket(limit: 1, filter: "name=ilike=test") {
        id
        name
        status {
            id
            name
        }
    }
}

Exemple de croisement entre schémas :

query {
    CartridgeItem {
        id
        name
         printer_models {
            name
            # the product number is not usually returned by the REST API, but is available in GraphQL since you can access the full PrinterModel schema here.
            product_number
        }
    }
}

Vous pouvez explorer les schémas en utilisant des requêtes GraphQL standard telles que :

query {
    __schema {
        types {
            name
            description
            fields {
                description
                type {
                    name
                    description
                }
            }
        }
    }
}

Alternativement, une interface API REST est disponible pour les déclarations brutes de type GraphQL à l’aide d’une requête GET./api.php/GraphQL/Schema

Comme c’est la norme avec GraphQL, vous DEVEZ spécifier chaque propriété que vous souhaitez revenir.

Pour plus d’informations sur GraphQL, consultez la documentation GraphQL.

Versionnement API

L'API est versionnée par le chemin URL. Si aucune version n'est spécifiée, la dernière version sera utilisée. Si vous spécifiez v1, votre requête sera acheminée vers l'API héritée, tandis que v2 et les versions ultérieures seront acheminées vers l'API de haut niveau. Exemple : /api.php/v2/...

Stratégie de fixation des versions

Lorsque vous spécifiez une version dans l'URL, l'API utilise les règles suivantes pour déterminer la version à utiliser :

• Si seule une version majeure est spécifiée, la dernière version mineure sera utilisée. Par exemple, /api.php/v2/... peut utiliser la version v2.1 s'il s'agit de la dernière version.

• Si une version majeure et une version mineure sont spécifiées, la dernière version de correctif sera utilisée. Par exemple, /api.php/v2.1/.. . peut utiliser la version v2.1.3 s'il s'agit de la dernière version.

• Si une version majeure, mineure et corrective est spécifiée, cette version exacte sera utilisée. Par exemple, /api.php/v2.1.3/... utilisera la version v2.1.3.

En général, il suffit de spécifier uniquement la version majeure et cela ne devrait pas perturber votre application lorsque de nouvelles versions sont publiées, tant qu'une version prise en charge est disponible.