Conventions de l'API REST

L'API REST IBM® UrbanCode Release respecte un ensemble de conventions pour assurer la cohérence de l'interaction.

URL REST

Chaque type d'élément sur le serveur est représenté comme une URL de niveau supérieur avec une forme plurielle. Dans la plupart des cas, l'URL utilise les mêmes termes que dans l'interface utilisateur UCR, formatés avec la convention de casse mixte. Par exemple, les types de changement sont représentés à l'URL http://url_base/changeTypes/, les réserves d'environnement sont à l'URL http://url_base/environmentReservations/, et les applications sont à l'URL http://url_base/applications/, où url_base est le nom d'hôte et le chemin vers le serveur.

En-têtes HTTP obligatoires

La plupart des opérations de l'API REST acceptent une entrée au format JSON, revoivent une sortie au format JSON, ou les deux. Conformément aux conventions HTTP, l'en-tête de requête Content-Type est nécessaire pour les opérations qui fournissent l'entrée JSON, et l'en-tête de requête Accept est nécessaire pour les opérations qui produisent la sortie JSON, avec la valeur de type de support application/json. Pour plus de commodité pour les développeurs, la méthode GET pour les listes et les éléments individuels (décrite ci-dessous) produit également une sortie JSON si le type de support est text/html et le paramètre de requête json est annexé à l'URL de requête avec n'importe quelle valeur. Ce paramètre est utile pour rendre la sortie JSON à partir d'un navigateur Web sans outils spéciaux pour modifier l'en-tête Accept. Par exemple, pour afficher la sortie JSON pour toutes les applications, entrez http://url_base/applications/?json dans la barre d'adresse d'un navigateur Web.

Propriété `id`

Des éléments tels que les applications ont une propriété d'identification unique (UUID), qui apparaît dans la représentation de l'objet JSON en tant que propriété id comme une chaîne de JSON. Vous pouvez faire référence à un élément spécifique par son UUID. Vous pouvez utiliser cet UUID dans des endroits comme les URL d'opérations d'API REST et dans les représentations JSON d'éléments.

Opérations de base

Les opérations de base de création, lecture, mise à jour et suppression sont fournies conformément aux conventions communes de l'API REST. L'URL de niveau supérieur pour un type d'élément représente la collecte des éléments de ce type. Pour rendre la liste de tous les éléments de ce type sous la forme d'un tableau d'objets JSON, utilisez la méthode HTTP GET avec les en-têtes HTTP appropriés ou le paramètre de requête json. Pour créer un nouvel élément, utilisez la méthode HTTP POST dans l'URL de niveau supérieur pour le type approprié, et fournissez des données JSON pour l'élément dans le corps de la requête. Le corps de la réponse inclut une représentation JSON complète du nouvel élément, y compris la propriété générée par le serveur id. Vous pouvez également fournir un tableau d'objets JSON pour créer plusieurs éléments en une seule demande. Dans ce cas, le corps de la réponse contient un tableau JSON des nouveaux éléments dans le même ordre qu'ils ont été fournis dans la demande. De même, vous pouvez mettre à jour les données de plusieurs éléments en utilisant la méthode HTTP PUT avec un tableau d'éléments JSON. Vous pouvez supprimer plusieurs éléments à l'aide de la méthode HTTP DELETE avec un tableau JSON qui contient des éléments JSON complets ou uniquement les UUID de ces éléments.

Pour exécuter une opération sur un seul élément existant, ajoutez l'UUID de l'élément à l'URL de niveau supérieur pour le type. Par exemple, pour accéder aux données JSON pour l'échantillon d'édition qui est fourni, utiliser la méthode HTTP GET avec l'URL http://url_base/releases/00000000-0000-0000-0000-000000000036/. Pour mettre à jour les données relatives à un élément, utilisez la méthode HTTP PUT, et indiquez un objet JSON mis à jour dans le corps de la demande. (Dans ce cas, l'UUID dans de l'URL de requête prévaut sur la propriété id dans le corps de la requête.) Pour supprimer l'élément, utilisez la méthode HTTP DELETE ; aucun corps de requête n'est nécessaire dans ce cas.

Formats de sortie

Lorsque vous utilisez les opérations créer, lire et mettre à jour (POST, GET et PUT), vous pouvez inclure le paramètre de requête facultatif format pour régler la sortie JSON pour les cas d'utilisation spécifiques. Si vous ne fournissez pas ce paramètre, ou si la valeur du paramètre n'est pas reconnue, un format par défaut est utilisé. Chaque type d'élément prend en charge un ensemble différent de formats ; ces formats sont listés avec les informations de référence pour le type d'élément. Certains formats montrent une grande quantité de détails et d'autres montrent une petite quantité de détails, mais la différence est uniquement dans les informations qui sont représentées ; les valeurs sont les mêmes.

Vous pouvez utiliser les formats list et detail avec n'importe quel type d'élément. Le format list offre des informations récapitulatives, comme vous pourriez les afficher dans un tableau d'éléments. Le format detail fournit des informations plus détaillées. Ce format comprend généralement le contenu des éléments associés. Pour certains éléments, ces formats sont identiques. En outre, les types d'éléments qui ont une propriété name ont également un format name. Ce format comprend uniquement les propriétés id et name, ce qui peut être utile pour afficher une liste d'éléments pour la sélection par nom. Par commodité, le format name pour un type d'élément peut également être produit en ajoutant name à l'URL de niveau supérieur pour le type, par exemple, GET http://url_base/applications/name.

Conventions d'entrée JSON

Lorsque vous fournissez des données JSON comme entrée pour les opérations créer ou mettre à jour, l'API REST ne tient compte que des propriétés qui sont inscriptibles sur l'élément. L'API ignore toutes les autres données. Les propriétés en lecture seule, telles que les nombres calculés ou les dates de création, ne sont pas mises à jour. L'API ignore les propriétés non reconnues. Les propriétés des éléments connexes, autres que la propriété id, utilisées pour établir une référence, ne sont pas non plus mises à jour.

Par exemple, supposons que vous indiquez l'entrée JSON suivante pour créer une édition :

{
  "name": "Nouvelle édition",
  "team": { 
    "id": "00000000-0000-0000-0000-000000000206", 
    "name": "Pas le nom de l'équipe réel" },
  "lifecycleModel": "00000000-0000-0000-0000-000000000006",
  "totalChanges": 42,
  "BadProperty": "xxxx"
}

Lorsque l'API traite cette entrée, elle ne reconnaît que les propriétés qui sont nécessaires pour créer une édition. Par conséquent, elle ignore la propriété non reconnue BadProperty et la valeur calculée totalChanges. Dans ce cas, l'entrée ci-dessus est équivalente à l'entrée plus simple ci-dessous :

{
  "name": "Nouvelle édition",
  "team": "00000000-0000-0000-0000-000000000206",
  "lifecycleModel": "00000000-0000-0000-0000-000000000006"
}

De même, lorsque vous mettez à jour un élément existant, l'API change uniquement les propriétés que vous spécifiez dans l'entrée JSON. L'API ne modifie pas les propriétés que vous omettez. Pour effacer la valeur d'une propriété, spécifiez une valeur nulle explicite JSON pour cette propriété.

Par exemple, envisagez un changement existant avec le contenu suivant :

{
  "id": "00000000-0000-0000-0000-123456789000",
  "name": "Nouvelle fonction",
  "description": "",
  "status": "In Progress",
  "type": {
    "id":"00000000-0000-1201-0000-000000000001", 
    "name":"Fonction", 
    "icon":"feature"}
}

L'entrée suivante associe la modification à l'échantillon d'édition, mais ne met pas à jour les autres propriétés de la modification.

{
  "id": "00000000-0000-0000-0000-123456789000",
  "release": "00000000-0000-0000-0000-000000000036"
}

Pour inverser cette opération et effacer l'association de cette modification à l'échantillon d'édition, vous pouvez utiliser l'entrée suivante :

{
  "id": "00000000-0000-0000-0000-123456789000",
  "release": null
}

Références

Dans la plupart des cas, vous pouvez faire référence à un seul élément avec une chaîne JSON qui contient l'UUID de l'élément ou un objet JSON qui contient une propriété id avec la même valeur. Comme décrit ci-dessus, les autres propriétés de l'élément référencé sont ignorées. Par exemple, tous les objets JSON suivants sont équivalents lorsque vous associez une modification à une édition.

{
  "id": "00000000-0000-0000-0000-123456789000",
  "release": "00000000-0000-0000-0000-000000000036"
}

{
  "id": "00000000-0000-0000-0000-123456789000",
  "release": {"id":"00000000-0000-0000-0000-000000000036"}
}

{
  "id": "00000000-0000-0000-0000-123456789000",
  "release": {
    "id":"00000000-0000-0000-0000-000000000036", 
    "name":"Exemple d'édition"}
}

{
  "id": "00000000-0000-0000-0000-123456789000",
  "release": {
    "id":"00000000-0000-0000-0000-000000000036", 
    "name":"Pas le nom d'édition réel"}
}

Références à valeurs multiples (collection)

Certaines relations peuvent avoir plusieurs valeurs. Par exemple, une seule édition peut être associée à plusieurs applications. Dans certains cas, ces relations ne sont pas mises à jour lorsque vous créez ou mettez à jour le côté de valeur unique de la relation. Par exemple, lorsque vous créez une édition, les valeurs que vous fournissez pour la propriété applications n'ont aucun impact. Au lieu de cela, utilisez d'autres URL pour ajouter ou supprimer des applications des éditions :

Énumérez les applications qui sont liées à une édition : GET /releases/{IDédition}/applications
Ajoutez une application à une édition : POST /releases/{IDédition}/applications/{IDapplication}
Supprimez une application d'une édition : DELETE /releases/{IDédition}/applications/{IDapplication}

Cependant, dans d'autres cas, en particulier si un élément nécessite une relation spécifique, vous pouvez spécifier l'entrée pour le côté valeur unique de la relation. Par exemple, une application peut être associée à plusieurs équipes. Dans ce cas, lorsque vous créez une application, vous pouvez fournir un tableau JSON de chaînes UUID pour la propriété "teams". Il n'existe pas d'URL spéciales pour manipuler cette relation.

Propriétés de valeur de clé

Certains types d'éléments prennent en charge le stockage et la récupération de paires clé-valeur à structure libre en plus des propriétés définies statiquement. Ce type de propriété représente souvent des données qui sont liées à un fournisseur d'intégration. Par exemple, un changement qui représente un élément de travail IBM Rational Team Concert pourrait stocker l'identificateur pour l'élément de travail en tant que propriété dans ce stockage clé-valeur.

Les propriétés clé-valeur sont représentées dans les données JSON comme un élément lié dans la propriété properties. Par exemple, le code suivant est un changement avec des propriétés clé-valeur qui sont nommées first, second, et third :

{
  "id": "00000000-0000-0000-0000-123456789000",
  "name": "Nouvelle fonction",
  "description": "",
  "status": "In Progress",
  "type": {
    "id":"00000000-0000-1201-0000-000000000001", 
    "name":"Fonction", 
    "icon":"feature"},
  "properties": { 
    "first":"first value", 
    "second":"second value", 
    "third":"third value"}
}

La clé et la valeur doivent être représentées en tant que chaînes JSON. Comme avec des propriétés définies statiquement, si une clé est omise de l'entrée, les opérations de mise à jour ne la changent pas. Pour effacer une paire clé-valeur, affectez une valeur nulle JSON à la clé.

Pagination

Pour certains types d'éléments, la requête GET de niveau supérieur peut fournir un sous-ensemble d'éléments plutôt que la liste complète. La récupération de sous-ensembles d'éléments de ce type est communément appelée "pagination" car elle implique le chargement d'une seule "page" de données dans chaque requête.

Deux autres formes de pagination sont disponibles, en utilisant les paramètres de la requête ou l'en-tête HTTP Range.

Pour utiliser les paramètres de requête pour la pagination, spécifiez un paramètre de requête rowsPerPage et pageNumber dans la requête HTTP GET. Pour récupérer la première page, indiquez le code pageNumber=1. Par exemple, pour récupérer les cinq premières applications, utilisez la requête GET http://url_base/applications/?rowsPerPage=5&pageNumber=1.

Pour utiliser l'en-tête Range HTTP, spécifiez les valeurs de début et de fin pour la gamme d'éléments, en spécifiant les valeurs basées sur zéro et les valeurs inclusives. FPar exemple, pour extraire les cinq premières applications, ajoutez l'en-tête suivant à la requête GET http://url_base/applications/ :

Range: items=0-4

Indépendamment de la façon dont vous demandez la pagination, la réponse HTTP utilise l'en-tête Content-Range pour spécifier la gamme actuelle qui est récupérée et le nombre total d'éléments disponibles. Par exemple, si vous avez demandé les cinq premières modifications d'une liste de 10, la réponse contient l'en-tête suivant :

Content-Range: 0-4/10

Si vous avez demandé les cinq premières modifications, et seules trois modifications sont disponibles, l'en-tête ressemble à ceci :

Content-Range: 0-2/3

Tri

Pour trier les résultats de l'opération GET de niveau supérieur, spécifiez les paramètres orderField et sortType. Le paramètre orderField doit contenir le nom d'une propriété de tri. Le paramètre sortType doit contenir la valeur asc pour trier en ordre croissant ou la valeurdesc pour trier en ordre décroissant.

Pour trier sur les propriétés des éléments connexes, indiquez le nom de la propriété au format en pointillés. Par exemple, pour trier la liste des modifications en fonction de la mise en production associée, spécifiez la valeur release.name. L'ordre n'est pas précisé si une propriété dans ce chemin a la valeur null.

Vous pouvez combiner le tri à la pagination et le paramètre format. Par exemple, pour récupérer les cinq premières modifications au format detail triées par le nom de l'édition associée dans l'ordre croissant, utilisez la requête suivante :

GET http://url_base/changes/?format=detail&rowsPerPage=5&
  pageNumber=1&orderField=release.name&sortType=asc

Certaines propriétés ne peuvent être utilisées pour le tri. En particulier, les propriétés qui représentent des données récapitulatives, telles que le nombre d'éléments, ne peuvent généralement pas être utilisées pour le tri.

Filtrage

Pour filtrer les résultats, indiquez les paramètres de requête. Le nom de certains paramètres de requête est basé sur celui des propriétés de données sur lesquelles vous filtrez les résultats. Par exemple, la requête suivante affiche les éditions créées à une date indiquée :

GET http://_url_de_base/releases/
  ?filterFields=dateCreated
  &filterType_dateCreated=gt
  &filterClass_dateCreated=Long
  &filterValue_dateCreated=1421171883574
  &orderField=dateCreated
  &sortType=asc

Cet exemple utilise les paramètres de requête suivants :

filterFields

Ce paramètre spécifie les zones sur lesquelles les résultats sont filtrés. Dans l'exemple précédent, le code filterFields=dateCreated filtre les résultats par date spécifique. Pour filtrer plusieurs zones, utilisez ce paramètre à chaque reprise, comme dans l'exemple suivant :

filterFields=dateCreated&filterFields=name

filterType_nom_de_propriété

Ce paramètre spécifie le type d'opération de filtrage à exécuter sur la propriété spécifiée. Dans l'exemple précédent, la valeur de la propriété était filterType_dateCreated=gt. Ce code indique que le filtre pour la propriété dateCreated affiche les valeurs postérieures à la date spécifiée. Les opérations de filtrage prises en charge sont : like, eq (égal à), ne (non égal à), gt (supérieur à), ge (supérieur ou égal à), lt (inférieur à), le (inférieur ou égal à), null, notnull, range, et in.

filterClass_nom_de_propriété

Cette propriété indique le type de données fourni pour le filtrage. Dans l'exemple précédent, la date était fixée à l'aide d'un entier long dans une valeur d'horodatage d'Unix : filterClass_dateCreated=Long. Les types de données valides sont Boolean, Long, String, UUID, et Enum.

Chaque type de données prend en charge un ensemble spécifique de types de filtre :

String : like, eq, ne, gt, ge, lt, le, null, notnull, range, et in
Long : eq, ne, gt, ge, lt, le, null, notnull, range, et in
Boolean : eq, ne, null, notnull
UUID : eq, ne, null, notnull
Enum : eq, ne, null, notnull

filterValue_nom_de_propriété

Ce paramètre indique la valeur sur laquelle les résultats sont filtrés. Dans l'exemple suivant, la date donnée était au format d'horodatage d'Unix. Si vous utilisez les types de filtre range ou in, indiquez ce paramètre à diverses reprises pour définir la plage ou l'ensemble de valeurs. Aucun paramètre n'est nécessaire pour les filtres de type null et notnull.

Feedback