# 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](https://glpi-install.readthedocs.io/en/latest/install/index.html#files-and-directories-locations) 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 ` ### 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](https://glpi-install.readthedocs.io/en/latest/install/index.html#files-and-directories-locations) 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 : ``. Pour certains opérateurs, il n'y a pas de valeur, la syntaxe est donc simplement ``. ### 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 : ```graphql query { Ticket(limit: 1, filter: "name=ilike=test") { id name status { id name } } } ``` Exemple de croisement entre schémas : ```graphql 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 : ```graphql 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](https://graphql.org/learn/). ## 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. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://help.glpi-project.org/documentation/fr/modules/configuration/general/api/restful-api-v2.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.