6.1.1. Général

Ceci est l’API REST standard pour les programmes externes qui veulent interagir avec Bugzilla. Elle fournit une interface REST pour diverses fonctions de Bugzilla.

6.1.1.1. Informations basiques

Navigation

Si l’en-tête Accept d’une requête est défini à text/html (comme c’est le cas pour un navigateur Web ordinaire) alors l’API renverra les données JSON sous forme d’une page HTML que le navigateur pourra afficher. En d’autres termes, vous pouvez jouer avec l’API en utilisant juste votre navigateur pour voir les résultats sous une forme lisible. C’est un bon moyen pour essayer les divers appels GET, même si vous ne pouvez pas les utiliser pour POST ou PUT.

Format de données

L’API REST supporte seulement des données d’entrée en JSON, et les sorties en JSON ou JSONP. Par conséquent, les objets envoyés et reçus doivent être au format JSON.

Pour chaque requête, vous devez définir les en-têtes HTTP Accept et Content-Type pour le type MIME du format des données que vous utiliser pour communiquer avec l’API. Content-Type dit à l’API comment interpréter votre requête et Accept indique le format de données que vous souhaitez avoir en retour. Content-Type doit être de type application/json. Accept peut avoir le type précédent ou application/javascript pour JSONP. Dans ce dernier cas, ajoutez un paramètre callback pour donner un nom à vos données de retour.

Les paramètres peuvent aussi être passés dans la chaîne de requête pour les requêtes autres que GET et surchargeront les paramètres correspondants dans le corps de la requête.

Exemple de requête renvoyant la version courante de Bugzilla :

GET /rest/version HTTP/1.1
Host: bugzilla.example.com
Accept: application/json

Exemple de réponse :

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json

{
  "version" : "4.2.9+"
}

Erreurs

Quand une erreur survient sur REST, un objet est renvoyé avec la clé error définie à true.

Le contenu de l’erreur est similaire à ceci :

{
  "error": true,
  "message": "Un message ici",
  "code": 123
}

6.1.1.2. Types de données communes

L’API de Bugzilla utilise les différents types de paramètres suivants :

type	description
int	Entier.
double	Nombre à virgule flottante.
string	Chaîne.
email	Chaîne représentant une adresse électronique. Cette valeur quand elle est renvoyée, peut être filtrée en indiquant si l’utilisateur est connecté ou pas.
date	Une date spécifique. Exemple de format : `AAAA-MM-JJ`.
datetime	Une date/heure spécifique. Le fuseau horaire doit être en UTC sauf mention contraire. Exemple de format : `AAAA-MM-JJTHH24:MI:SSZ`.
boolean	`true` ou `false`.
base64	Une chaîne encodée en base64. C’est le seul moyen de transférer des données binaires via l’API.
array	Un tableau. Il peut y avoir différent types dans un tableau. `[` et `]` sont utilisés pour représenter le début et la fin des tableaux.
object	Une correspondance de clés et de valeurs, appelée `hash`, `dict` ou `map` dans d’autres langages de programmation. Les clés sont des chaînes et les valeurs peuvent être de tout type. `{` et `}` sont utilisés pour représenter le début et la fin des objets.

Les paramètres obligatoires sont indiqués en gras dans la table des paramètres pour chaque méthode d’API.

6.1.1.3. Authentification

Certaines méthodes ne nécessitent pas d’être connecté. Par exemple : Obtention d’un bogue. Cependant, en vous authentifiant, vous pourrez voir des informations non publiques, par exemple, un bogue qui n’est pas visible pour tous.

Il existe deux façons de vous authentifier :

Les clés d’API

Vous pouvez spécifier Bugzilla_api_key ou simplement api_key en argument pour tout appel, et vous serez connecté en tant que cet utilisateur si la clé est correcte et n’a pas été révoquée. Vous pouvez définir une clé d’API en utilisant l’onglet Clé d'API dans la page des Préférences.

Identifiant et mot de passe

Vous pouvez spécifier Bugzilla_login et Bugzilla_password ou simplement login et password respectivement, comme argument de tout appel, et vous serez connecté en tant que cet utilisateur si l’identifiant et le mot de passe sont corrects.

nom	type	description
Bugzilla_login	string	Un identifiant de connexion d’un utilisateur.
Bugzilla_password	string	Le mot de passe de cet utilisateur.
Bugzilla_restrictlogin	boolean	Si défini à true, alors votre identifiant ne sera valide que pour votre adresse IP.

L’option Bugzilla_restrictlogin n’est utilisée que si vous avez également spécifié Bugzilla_login et Bugzilla_password.

Il existe aussi une méthode d’authentification obsolète décrite ci-dessous qui sera supprimée dans la version suivant Bugzilla 5.0.

Les jetons Bugzilla

Vous pouvez utiliser Connexion pour vous connecter en tant qu’utilisateur de Bugzilla. Ceci délivre un jeton qui devra être utilisé dans les futurs appels. Utilisez la valeur pour token et passez Bugzilla_token ou simplement token comme arguments d’un appel API.

nom	type	description
Bugzilla_token	string	Vous pouvez spécifier ceci comme argument d’un appel, et vous serez connecté en tant que cet utilisateur si le jeton est correct. Ceci est le jeton renvoyé en appelant Connexion mentionné ci-dessus.

Une erreur est renvoyée si le jeton est invalide ; vous devrez vous connecter à nouveau pour obtenir un nouveau jeton.

À compter de Bugzilla 5.0, les cookies de connexion ne seront plus renvoyés par Connexion pour des raisons de sécurité.

6.1.1.4. Paramètres utiles

Beaucoup d’appels prennent des arguments courants. Ceux-ci sont documentés ci-dessous et liés aux appels individuels où ces paramètres sont utilisés.

Inclure les champs

Beaucoup d’appels renvoient un tableau d’objets avec divers champs dans les objets. (Par exemple, Obtention d’un bogue renvoie une liste de bogues ayant des champs tels que id, summary, creation_time, etc.)

Ces paramètres permettent de limiter les champs présents dans les objets, pour améliorer les performances ou économiser de la bande passante.

include_fields: Les noms (sensibles à la casse) des champs dans les données de réponse. Seuls les champs spécifiés seront renvoyés, les autres ne seront pas inclus. Les champs doivent être délimités par des virgules.

Les noms de champs invalides sont ignorés.

Exemple de requête pour Obtention d’un utilisateur :

GET /rest/user/1?include_fields=id,name

renverrait quelque chose comme ceci :

{
  "users" : [
    {
      "id" : 1,
      "name" : "user@domain.com"
    }
  ]
}

Exclure les champs

exclude_fields : Les noms (sensibles à la casse) des champs dans les données de réponse. Les champs spécifiés ne seront pas renvoyés dans la réponse. Les champs doivent être séparés par des virgules.

Les noms de champs invalides sont ignorés.

Les champs spécifiés ici surpassent ceux indiqués dans include_fields. Donc si vous indiquez un champ dans les deux, il sera exclu.

Exemple de requête pour Obtention d’un utilisateur :

GET /rest/user/1?exclude_fields=name

renverrait quelque chose comme ceci :

{
  "users" : [
    {
      "id" : 1,
      "real_name" : "John Smith"
    }
  ]
}

Certains appels supportent la spécification de « sous-champs ». Si un appel déclare qu’il gère les restrictions de « sous-champs », vous pouvez restreindre les informations renvoyées dans le premier champ. Par exemple, si vous appelez Obtention de produit avec un include_fields de components.name, alors, seul le nom du composant sera renvoyé (et rien d’autre). Vous pouvez inclure le champ principal et exclure le sous-champ.

Il existe plusieurs raccourcis d’identifiants pour demander d’inclure ou d’exclure des groupes de champs :

valeur	description
_all	Tous les champs possibles sont renvoyés si ceci est spécifié dans `include_fields`.
_default	Les champs par défaut sont renvoyés si `include_fields` est vide ou si ceci est spécifié. C’est utile si vous voulez les champs par défaut en plus d’un champ qui n’est pas renvoyé normalement.
_extra	Les champs supplémentaires ne sont pas renvoyés par défaut et doivent être manuellement spécifiés dans `include_fields` en indiquant leur nom exact ou en ajoutant `_extra`.
_custom	Les champs personnalisés sont normalement renvoyés par défaut à moins que ceci ne soit ajouté dans `exclude_fields`. Vous pouvez aussi l’utiliser dans `include_fields` si par exemple vous voulez des noms de champs spécifiques en plus de tous les autres champs personnalisés. Les champs personnalisés sont normalement seulement relatifs aux objets bogues.

Cette documentation contient très probablement des bogues ; si vous en découvrez, veuillez les signaler ici.