Métadonnées Gist API¶

L'API Gist des métadonnées est une API JSON RESTful en lecture uniquement qui permet de récupérer et de parcourir des métadonnées. Les éléments de cette API contiennent la gist du même élément dans l'API Métadonnées.

L'API est spécifiquement conçue pour éviter :

• des réponses volumineuses en raison de l'inclusion de graphes d'objets partiels imbriqués.
• Traitement des demandes en mémoire, à forte intensité de ressources (par exemple, le filtrage en mémoire ou la navigation dans le graphe d'objets).
• n + 1 requêtes de base de données à la suite de la navigation dans le graphe d'objets lors de la restitution de la réponse.

Comparaison avec l'API des métadonnées¶

L'API standard des métadonnées est une API flexible et puissante, conçue pour répondre à tous les cas d'utilisation. L'inconvénient est que toutes les fonctionnalités et combinaisons ne peuvent pas être mises à l'échelle tout en conservant de bonnes performances en présence d'un grand nombre d'éléments. En particulier, les listes d'éléments où chaque élément possède une propriété qui est une grande collection d'objets complexes se sont avérées problématiques car elles font rapidement référence à une grande partie du graphe d'objets entier.

L'API /gist a été ajoutée pour fournir une API de métadonnées où la mise à l'échelle est notre première priorité. L'inconvénient est qu'il y a des limites plus distinctes à ce qui est techniquement raisonnable, ce qui signifie que toutes les fonctionnalités de l'API standard de métadonnées n'existent pas pour l'API Gist.

L'API Gist utilise une stratégie de division et de conquête pour éviter les réponses avec de grands graphes d'objets partiels. Au lieu d'inclure des objets ou des listes imbriqués, elle fournit un URI de point de terminaison /gist où cet objet ou cette liste peut être visualisé de manière isolée.

L'API /gist se réfère aux données imbriquées en utilisant les URI plutôt que de les inclure. Cela signifie que si un client est intéressé par ces informations imbriquées, il faudra plus de requêtes, mais chacune d'entre elles reste raisonnablement petite et s'adaptera bien dans le contexte d'un grand nombre d'éléments potentiels.

Les différences connues :

• les éléments n'incluent que les champs des objets identifiables référencés si ceux-ci n'ont pas de point de terminaison propre
• ils n'incluent jamais directement les collections d'objets identifiables
• les éléments par défaut n'incluent pas tous les champs disponibles, mais un sous-ensemble qui dépend du contexte et des paramètres
• les listes ne peuvent pas être utilisées sans pagination (il n'y a donc pas de paramètre pagination)
• les champs avec les collections ne sont pas paginés en utilisant le transformateur pagination mais à travers un point de terminaison API paginé pour la propriété particulière de la collection
• les éléments d'une liste, la taille d'une propriété de collection ou le résultat d'un transformateur booléen prennent toujours en compte le partage d'objets (l'ensemble des éléments pris en compte est toujours l'ensemble visible par l'utilisateur)
• Gist propose les transformateurs de champs de collection membre(<id>) et non-membre(<id>)
• Gist propose un filtre de vérification d'accès de type peutLire et peuModifier au lieu de filtrer selon la propriété accès
• La Gist propose d'utiliser les UID des attributs comme noms de champs et de propriétés de filtrage pour permettre l'établissement de listes ou le filtrage en fonction de valeurs d'attributs personnalisées
• Gist propose le regroupement de filtres

Les limites connues :

• par défaut, seuls les champs persistants sont inclus ; une poignée de champs spéciaux non persistants (champs synthétiques) peuvent être ajoutés explicitement ; d'autres les champs non persistants peuvent être extraits à l'aide de la transformation de
• les filtres ne peuvent être appliqués qu'aux champs persistants
• les commandes ne peuvent être appliquées qu'aux champs persistants
• les filtres de jeton ne sont pas disponibles
• l'ordre est toujours sensible à la casse
• Le transformateur pluck limité aux propriétés de texte
• Les champs contenant des collections d'éléments simples (non identifiables) ne peuvent pas toujours être inclus en fonction de la manière dont ils sont stockés

Lorsque cela est possible, l'utilisation de l'API /gist doit être considérée comme la meilleure façon d'obtenir des informations sur les métadonnées.

Points de terminaison¶

L'API /gist a 3 types de points de terminaison :

• /api/<object-type>/gist : liste paginée de tous les objets connus et visibles du type (implicite auto=S)
• /api/<object-type>/<object-id>/gist : affichage d'un seul objet par identifiant (implicite auto=L)
• /api/<object-type>/<object-id>/<field-name>/gist : liste paginée de tous les éléments connus et visibles dans la collection du champ de l'objet propriétaire (implicite auto=M ; dans le cas d'un champ simple, juste la valeur du champ).

Ces points de terminaison correspondent aux points de terminaison de l'API standard de métadonnées sans le suffixe /gist et partagent la majorité des paramètres et de leurs options avec cette API.

Données de navigation¶

Puisque l'API /gist évite les structures de données profondément intégrées dans la réponse, les détails des objets complexes ou des listes d'objets référencés sont plutôt fournis sous la forme d'un URI vers le point de terminaison gist qui renvoie uniquement l'objet complexe ou la liste d'objets. Ces URI sont fournies par le champ pointsdeterminaisonsdel'api d'un élément qui est automatiquement ajouté à un élément lorsque de telles références existent. La propriété item elle-même peut contenir un résultat de transformation sur l'objet ou la collection tel que sa taille, sa contenance, sa non contenance, son (ses) identifiant(s) ou une propriété extraite telle que son nom.

Pour parcourir manuellement les données, il peut être pratique d'utiliser le paramètre absoluteUrls=true. Les liens entre les parties de la liste peuvent maintenant être suivis directement dans les navigateurs qui affichent les réponses JSON.

Paramètres¶

Tous les points de terminaison de l'API /gist acceptent le même ensemble de paramètres. Les paramètres et leurs options qui n'ont pas de sens dans le contexte du point de terminaison sont ignorés.

Aperçu¶

Les paramètres par ordre alphabétique :

Le paramètre absoluteUrls¶

Par défaut, les URIs dans les points de terminaison api, href et les membres précedent et suivant de lapagination sont relatifs, et commencent par le chemin /<object-type>/.

Les URI peuvent être changés en URL absolues en utilisant le paramètre absoluteUrls.

Par exemple, /api/users/rWLrZL8rP3K/gist?fields=id,href renvoie :

{
  "id": "rWLrZL8rP3K",
  "href": "/users/rWLrZL8rP3K/gist"
}

tandis que /api/users/rWLrZL8rP3K/gist?fields=id,href&absoluteUrls=true renvoie :

{
  "id": "rWLrZL8rP3K",
  "href": "http://localhost:8080/api/users/rWLrZL8rP3K/gist?absoluteUrls=true"
}

Comme le montre l'exemple, le paramètre absoluteUrls est également transmis ou reporté dans les URLs incluses, ce qui permet de parcourir les réponses en suivant les URLs fournies.

Le Paramètre auto¶

Chaque point d'accès définit implicitement une valeur par défaut pour l'étendue des champs correspondant au sélecteur de champs* / :tout :

• /api/<object-type>/gist : implique que auto=S
• /api/<object-type>/<object-id>/gist: implique que auto=L
• /api/<object-type>/<object-id>/<field-name>/gist: implique que auto=M

Le paramètre auto est utilisé pour surcharger manuellement la valeur par défaut afin que les éléments de la liste incluent plus ou moins de champs. Ce paramètre agit à nouveau comme une valeur par défaut qui peut être modifiée pour chaque champ à l'aide d'une transformation explicite.

Les options possibles pour auto sont (" les tailles de t-shirt ") :

• XS : inclut uniquement les identifiants et les propriétés textuelles
• S : exclut les propriétés complexes (objets), les collections sont uniquement liées (non comptabilisées)
• M : complexe inclus en tant qu'URL de référence, les références et les collections en tant qu'URL de comptage et de référence
• L : comme M mais les références et les collections sont incluses en tant qu'identifiants (OBS ! non consolidé en taille)
• XL : comme L mais les références et les collections sont incluses en tant qu'objets de l'identifiant : { "id" : <id>}

Par exemple, /api/users/gist listerait les éléments avec les champs identifiant, nom, prénom, numéro de téléphone, email, dernière mise à jour alors que /api/users/gist?auto=XS ne liste que l' identifiant, le nom, le prénom, le numéro de téléphone, l'email. L'utilisation de /api/users/gist?auto=L inclurait également unités d'organisation, unités d'organisation de visualisation des données, Unités d'organisation de recherche d'instances d'entités suivis et groupes d'utilisateurs, chacun avec la liste des identifiants des membres des listes/ensembles.

Le paramètre champs¶

Spécifie la liste des champs à inclure pour chaque élément de la liste.

Les champs sont inclus dans les résultats des objets JSON pour un élément dans l'ordre indiqué. Un preset dans la liste des champs est étendu aux champs qu'il contient en fonction de la position qu'il occupe dans la liste fields. Les champs de la présélection sont classés de simple à complexe.

Si aucun paramètre fields n'est fourni, fields=* est pris en compte. Notez que les champs du *preset dépendent également du paramètre auto.

Pour supprimer un champ, utilisez !<name> ou -<name> dans la liste des champs. Par exemple, pour supprimer les groupes d'utilisateurs d'un utilisateur, utilisez :

/api/users/gist?fields=*,!groupes d'utilisateurs

Le même principe peut être utilisé pour spécifier le transformateur à utiliser pour un champ. Par exemple, pour inclure les identifiants des groupes d'utilisateurs de l'utilisateur, utilisez :

/api/users/gist?fields=*,groupes d'utilisateurs:identifiants

Le paramètre champs permet de lister les champs des objets imbriqués. Par exemple, pour ajouter références de l'utilisateur avec identifiant et nom d'un utilisateur, utilisez :

/api/users/gist?fields=*,références de l'utilisateur[identifiant,Nom d'utilisateur]

Cela crée des éléments du genre :

{
  ...
  "références de l'utilisateur": {
    "identifiant": "Z9oOHPi3FHB",
    "Nom d'utilisateur": "invité"
  }
}

Lors de l'inclusion de champs imbriqués de collections, le champ imbriqué doit être une propriété textuelle.

Par exemple pour inclure tous les noms des groupes d'utilisateurs d'un utilisateur par :

/api/users/gist?fields=*,groupes d'utilisateurs[nom]

La liste des groupes d'utilisateurs est la suivante:

{
  "groupes d'utilisateurs ": {
    "nom": [
      "_PROGRAMME_Programme pour les patients hospitalisés",
      "_PROGRAMME_Programme TB",
      "_ENSEMBLE DE DONNÉES_Superutilisateur",
      "_PROGRAMME_Superutilisateur",
      "_ENSEMBLE DE DONNÉES_Agent de saisie des données",
      "_ENSEMBLE DE DONNÉES_Agent M et E"
    ]
  }
}

/api/users/gist?fields=*,groupe d'utilisateurs::pluck( nom)~renommer(groupe d'utilisateurs.nom)

Lorsque l'on demande un seul champ, comme /api/users/gist?fields=nom, la réponse est une liste (toujours paginée) de valeurs simples :

{
  "pager": {
    "page": 1,
    "taille de la page": 50
  },
  "utilisateurs": [
    "Kamara",
    "Wakiki",
    "Nana",
    "Malai",
    ...
  ]
}

Lorsque l'on demande un champ unique de l'objet d'un propriétaire spécifique qui a une valeur simple (sans collection), comme par exemple /api/users/rWLrZL8rP3K/gist fields=surname, la réponse comprend uniquement la valeur JSON simple:

"Wakiki"

Pour plus de détails sur les préréglages de champs, voir la section Champs.

Le paramètre filtre¶

Pour filtrer la liste des éléments renvoyés, ajoutez un ou plusieurs paramètres filtre.

Plusieurs filtres peuvent être spécifiés sous la forme d'une liste séparée par des virgules d'un seul paramètre ou comme de multiples paramètres filtre, chacun avec un seul filtre.

Il existe deux types de filtres :

• unitaire: <field>:<operator>
• binaire: <field>:<operator>:<value>

Un champ peut être :

• un champ persistant du type d'élément énuméré
• un champ maintenu d'un objet directement référencé (relation 1:1)
• l'UID d'un attribut

Les opérateurs unitaires disponibles sont les suivants :

Les opérateurs binaires disponibles sont les suivants :

Si la <value> d'un filtre in ou !in est une liste, il est donné sous la forme suivante [valeur1,valeur2,...], par exemple: groupes d'utilisateurs:dans:[fbfJHSPpUQD,cYeuwXTCPkU].

Toute comparaison >, >=, < <=, == ou != appliquée à un champ de collection avec une valeur numérique comparera la taille de la collection à la valeur, par exemple : groupes d'utilisateurs:gt:0.

Toute comparaison >, >=, < <=, == ou != appliquée à un champ de texte avec une valeur numérique entière comparera la longueur du texte à la valeur, par exemple : nom:eq:4 (nom a une longueur de 4).

Les opérateurs de recherche de motifs binaires disponibles sont les suivants :

Les opérateurs like et !like peuvent être utilisés soit en fournissant un terme de recherche, et dans ce cas la correspondance est toute valeur où le terme apparaît à tout endroit, soit en fournissant le motif de recherche en utilisant * comme nombre quelconque de caractères et ? comme caractère unique.

Tous les opérateurs de recherche de motifs nommés like sont sensibles à la casse. Tous les autres sont insensibles à la casse.

Notez que les filtres sur les valeurs d'attributs utilisent une comparaison basée sur le texte, ce qui signifie que tous les filtres textuels sont pris en charge.

Par exemple, pour ne répertorier que les organisations de deuxième niveau, utilisez

/api/organisationUnits/gist?filter=level:eq:2

De même, lorsqu'il s'agit de lister les enfants d'une unité d'organisation particulière, la collection peut être filtrée. Pour ne lister que les enfants qui sont connectés à à un programme, on peut utiliser:

/api/organisationUnits/rZxk3S0qN63/children/gist?filter=programs:gt:0

Opérateurs binaires pour le filtrage basé sur l'accès (le partage) :

Lorsque l'identifiant de l'utilisateur <value> est omis, la vérification est effectuée pour l'utilisateur actuellement connecté. De même, si <value0> est omis pour le filtre peutAccéder, la vérification est effectuée pour l'utilisateur actuellement connecté.

Lorsqu'il est appliqué à une propriété de valeur simple, ici code, le filtre limite la réponse à ces éléments de données (propriétaire de l'objet) que l'utilisateur peut lire/modifier :

/api/dataElements/gist?filter=code:canWrite:OYLGMiazHtW

Lorsqu'il est appliqué à une propriété de référence, ici combinaison de catégories, le filtre limite la réponse à ces éléments de données ayant une combinaison de catégories que l'utilisateur peut lire/modifier:

/api/dataElements/gist?filter=categoryCombo:canWrite:OYLGMiazHtW

Lorsqu'il est appliqué à une propriété de collection de référence, ici groupe d'éléments de données, le filtre limite la réponse à ces éléments de données pour lesquels un groupe d'éléments de données existe dans la propriété de collection et que l'utilisateur peut lire/modifier :

/api/dataElements/gist?filter=dataElementGroups:canWrite:OYLGMiazHtW

La fonction peutAccéder demande deux arguments, le premier est l'identifiant de l'utilisateur, le second le modèle d'accès, par exemple, pour vérifier l'accès en lecture et en modification des métadonnées, le motif est rw% :

/api/dataElements/gist?filter=code:canAccess:[OYLGMiazHtW,rw%]

En outre, les filtres peuvent être regroupés pour permettre de combiner les filtres sélectionnés avec un OU logique lorsque le combinateur de filtre général est un ET logique, ou inversement avec un ET logique lorsque le combinateur général est un OU logique.

Pour les groupes, le modèle de filtre est élargi comme suit :

• unitaire: <group>:<field>:<operator>
• binaire: <group>:<field>:<operator>:<value>

Le groupe est un nombre arbitraire compris entre 0 et 9 (en cas d'omission, 0 est pris en compte).

La meilleure façon d'expliquer ce comportement est de donner un petit exemple pour un type d'objet imaginaire avec une propriété age et nom.

?filter=1:age:eq:50&filter=2:name:eq:foo&filter=2:name:eq:bar

Le filtre ci-dessus a deux groupes 1 et 2, et le groupe 2 a 2 membres. Ceci est équivalent au SQL (notez les et et ou ainsi que les accolades de regroupement) :

e.age = 50 and (e.name = 'foo' or e.name = 'bar')

Maintenant, si le même filtre est utilisé en combinaison avec rootJunction=OR

?filter=1:age:eq:50&filter=2:name:eq:foo&filter=2:name:eq:bar&rootJunction=OR

l'effet serait équivalent plutôt au code SQL suivant :

e.age = 50 or (e.name = 'foo' and e.name = 'bar')

Le paramètre sans titre¶

Les points d'extrémité qui renvoient une liste enveloppent par défaut les éléments dans une enveloppe contenant le pager et la liste, qui est nommée en fonction du type d'objet listé.

Par exemple, l'option /api/organisationUnits/gist renvoie :

{
  "pager": {
    "page": 1,
    "taille de la page": 50,
    "page suivante": "/organisationUnits/gist?page=2"
  },
  "unités d'organisation": [
    ...
  ]
}

Avec headless=true, la réponse à /api/organisationUnits/gist?headless=true est juste la partie de la liste [...] de l'exemple ci-dessus.

Le Paramètre inverse¶

Le inverse peut être utilisé dans le contexte d'un champ de collection gist de la forme /api/<object-type>/<object-id>/<field-name>/gist pour ne pas lister tous les éléments qui sont contenus dans la collection membre mais tous les éléments qui ne sont pas contenus dans la collection membre.

Par exemple, alors que

/api/organisationUnits/rZxk3S0qN63/children/gist

listerait toutes les unités d'organisation qui sont des enfants de rZxk3S0qN63 l'inverse

/api/organisationUnits/rZxk3S0qN63/children/gist?inverse=true

listerait toutes les unités d'organisation qui ne sont pas des enfants de rZxk3S0qN63. Cela pourrait par exemple être utilisé pour composer une liste de toutes les unités qui peuvent devenir des enfants d'une unité particulière.

Les filtres et les commandes s'appliquent normalement, c'est-à-dire qu'ils filtrent ou commandent les éléments non contenus dans la collection de membres.

Le paramètre local¶

Le paramètre locale est généralement utilisé à des fins de test pour changer de manière ad-hoc la langue de traduction des noms d'affichage.

Si elle n'est pas spécifiée, la langue de traduction est celle configurée dans les paramètres du compte de l'utilisateur.

Exemples:

/api/organisationUnits/gist?locale=en
/api/organisationUnits/gist?locale=en_GB

Le paramètre ordre¶

Pour trier la liste des éléments, une ou plusieurs expressions d'ordre peuvent être données.

Une expression d'ordre est soit un simple nom de champ persistant, soit un nom de champ suivi de :asc (ordre croissant - par défaut) ou de :desc (ordre décroissant).

Par exemple, pour trier les unités d'organisation par ordre alphabétique de nom, utilisez :

/api/organisationUnits/gist?order=name

L'ordre alphabétique inverse serait utilisé :

/api/organisationUnits/gist?order=name:desc

Pour trier les unités d'organisation en premier lieu par niveau, puis par nom, utilisez :

/api/organisationUnits/gist?order=level,name

On commencera par la (les) racine(s) au niveau 1. Pour commencer avec les unités foliaires, utilisez :

/api/organisationUnits/gist?order=level:desc,name

Si aucun ordre n'est spécifié, la liste des résultats aura un ordre stable basé sur l'organisation interne des données.

Le paramètre page¶

Fait référence à la page consultée dans la liste des pages, en commençant par 1 pour la première page.

Si le paramètre page n'est pas présent, il est égal à page=1.

La page est toujours en relation avec la taille de la page. Si une page est indiquée au-delà du nombre de correspondances existantes, une liste d'éléments vide est renvoyée.

Le paramètre taille de la page¶

Indique le nombre d'éléments d'une page. Le maximum est de 1000 éléments.

Si le paramètre taille de la page n'est pas présent, il est égal à taille de la page=50.

Le paramètre jonction de racines¶

Le paramètre jonction de racines peut être utilisé pour définir explicitement la jonction logique utilisée entre les filtres. Les possibilités sont les suivantes :

• ET : tous les filtres doivent correspondre à une donnée pour qu'elle soit incluse dans les résultats
• OU : l'un des filtres correspond à une donnée pour qu'elle soit incluse dans les résultats

La valeur par défaut est ET

Le paramètre total¶

Par défaut, une requête gist ne comptera pas le nombre total de correspondances si celles- ci dépassent la limite taille de la page. Au lieu de cela, nous acceptons les coûts supplémentaires que le comptage total implique.

Si l'on ne compte pas le nombre total de correspondances (Total=faux), la réponse pager suppose qu'il y a une page suivante dans le cas où des éléments taille de la page ont été trouvés. Ceci pourrait cependant s'avérer faux lorsque l'on navigue sur la page. De plus, le champ total indiquant le nombre de correspondances totales n'est pas inclus dans le pager.

Par exemple, /api/organisationUnits/gist renvoie un pager :

{
  "pager": {
    "page": 1,
    "taille de la page": 50,
    "page suivante": "/organisationUnits/gist?page=2"
  }
}

Lorsque l'on compte le nombre total de correspondances (Total=vrai), la réponse pager contiendra le champ total avec le nombre réel de correspondances totales au prix d'une opération supplémentaire sur la base de données.

La réponse à /api/organisationUnits/gist?total=true renvoie maintenant ce pager :

{
  "pager": {
    "page": 1,
    "taille de la page": 50,
    "total": 1332,
    "page suivante": "/organisationUnits/gist?total=true&page=2",
    "nombre de pages": 27
  }
}

Le paramètre traduire¶

Les champs tels que nom ou Nomcourt peuvent être traduits (internationalisés).

Par défaut, tout champ traduisible ayant une traduction est renvoyé traduit à condition que la langue de l'interface soit configurée par l'utilisateur qui demande la gist.

Pour retourner le champ non traduit, utilisez traduit=faux.

Par exemple, /api/organisationUnits/gist renvoie des éléments comme suit :

{
  "nom": "Un nom traduit",
  ...
}

Alors que /api/organisationUnits/gist?translate=false renverrait des éléments comme :

{
  "nom"
  "Nom du champ brut",
  ...
}

Notez que les champs synthétiques Afficher le nom et Afficher le nom court renvoient toujours la valeur traduite, indépendamment du paramètre traduire.

Champs¶

Les champs inclus par défaut (sans le paramètre champs) correspondent à champs=*. Cela signifie que la liste des champs affichés dépend du type d'objet, du contexte du point d'extrémité ainsi que du paramètre auto.

Notez que l'API /gist exclut toujours certains champs qui ne sont généralement pas importants pour les clients, comme par exemple les champs traductions ou partage. Ceux-ci peuvent être ajoutés explicitement.

Lorsqu'elle n'est pas explicitement fournie par un nom dans les paramètres champs, la liste des champs est calculée à partir d'un préréglage. Un préréglage peut être utilisé dans la liste des champs comme un nom de champ. Il se développe en zéro, un ou plusieurs champs en fonction du type d'objet, du point d'extrémité utilisé et du sélecteur.

Préréglages des champs¶

• * / :tous: les champs par défaut dépendent du contexte et du paramètre auto
• :identifiable : tous les champs maintenus de l'interface Objet identifiable
• :propriétaire : tous les champs maintenus pour lesquels le type listé est le propriétaire
• :nommable : tous les champs maintenus de l'interface ObjetNommable
• :maintenus : littéralement tous les champs maintenus

Transformateurs de champ¶

Un transformateur ou une transformation peut être appliqué à un champ en ajoutant l'un des indicateurs ::, ~ ou @ suivi de l'expression du transformateur.

Les expressions de transformateur disponibles sont les suivantes :

Un champ peut recevoir à la fois le transformateur renommer et l'un des autres transformateurs, par exemple :

/api/organisationUnits/gist?fields=*,children::size~rename(child-count)

Les éléments renvoyés n'ont plus de membre enfants mais un membre nombre-d'enfants à la place. Notez que renommer affecte aussi le nom du membre de la référence de l'URI donnée dans l'apidespointsd'Extrémités.

La transformation from peut être utilisée avec un ou plusieurs champs pérennes en paramètre. Ceux-ci seront chargés à partir de la base de données, définis dans une instance de l'objet élément listé avant que la propriété non pérenne transformée avec from ne soit extraite de cette instance en appelant le getter. Cela permet d'extraire des champs dérivés tout en utilisant la même logique que celle utilisée dans l'API de métadonnées habituelle.

Par exemple, le nom d'un utilisateur (propriété non pérenne) nom est composé des propriétés pérennes Prénom et nom. Il peut être obtenu de cette manière :

/api/users/gist?fields=id,name~from(firstName,surname)

Puisque le nom d'un utilisateur est un cas si commun, une auto-détection a été ajoutée pour que dans ce cas spécial, la transformation from soit ajoutée automatiquement à nom. Nous sommes autorisés à utiliser ce qui suit, qui ajoute en interne la transformation from :

/api/users/gist?fields=id,name

Bien que cela rende les propriétés non-perrennes accessibles en général, elles doivent toujours être incluses dans les champs de manière explicite. Pour un utilisateur, cela peut se faire de la manière suivante :

/api/users/gist?fields=*,name

Champs synthétiques¶

L'API /gist est étroitement liée aux propriétés qui existent dans la base de données. Cela signifie que les propriétés qui ne sont pas stockées dans la base de données ne sont généralement pas disponibles. L'exception à cette règle sont les propriétés "synthétiques" qui sont dynamiquement calculées sur la base d'une ou plusieurs propriétés stockées dans la base de données.

Les propriétés synthétiques sont disponibles pour tous les points d'extrémité où existent les propriétés maintenues nécessaires au calcul de la propriété synthétique.

A l'exception de la propriété points d'extrémité de l'api qui est automatiquement ajoutée si nécessaire toutes les autres propriétés synthétiques ne sont pas incluses par défaut et doivent faire l'objet d'une demande explicite dans la liste des champs.

Aperçu¶

Champs synthétiques par ordre alphabétique :

Le Champ href¶

Chaque élément d'une réponse /gist peut avoir un lien vers lui-même. Ce lien est donné dans la propriété href.

Pour ajouter le champ href, utilisez (par exemple) :

/api/<object-type>/gist?fields=*,href

Le champ afficherNom et afficherNomCourt¶

Par définition, le afficherNom est le nom traduit et le afficherNomCourt est le nom court traduit.

Pour ajouter afficherNom ou afficherNomCourt à la liste, utilisez (par exemple) :

/api/<object-type>/gist?fields=*,afficherNom
/api/<object-type>/gist?fields=*,afficherNomCourt

Notez que par défaut, toutes les propriétés traduisibles comme nom et nomCourt seront également traduites. Lorsque traduire=faux est utilisé pour désactiver cela, afficherNom et afficherNomCourt restent traduits.

Le Champ points d'extrémité de l'api¶

Cette propriété permet de parcourir des objets complexes ou des listes d'éléments qui sont inclus dans la réponse /gist sous la forme d'une valeur simple transformée comme un nombre d'éléments.

L'objet points d'extrémité de l'api aura un membre du même nom pour chaque membre de l'élément qui a été transformé en valeur simple.

Par exemple,

/api/users/gist?fields=id,userGroups::size,organisationUnits::size

renvoie les éléments du formulaire :

{
  "identifiant": "rWLrZL8rP3K",
  "groupes d'utilisateurs": 0,
  "unités d'organisation": 1,
  "points d'extrémité de l'api": {
    "unités d'organisation": "/utilisateurs/rWLrZL8rP3K/unités d'organisation/gist",
    "groupes d'utilisateurs": "/utilisateurs/rWLrZL8rP3K/groupes d'utilisateurs/gist"
  }
}

La liste des groupes d'utilisateurs et des unités d'organisation est incluse dans leur taille. Chacun a un membre correspondant dans points d'extrémité de l'api avec un chemin pour parcourir la liste.

Les chemins peuvent être transformés en URL en utilisant le paramètre Urls absolus.

/api/users/gist?fields=id,userGroups::size,organisationUnits::size&absoluteUrls=true

renvoie les éléments du formulaire :

{
  "identifiant": "rWLrZL8rP3K",
  "groupes d'utilisateurs": 0,
  "unités d'organisation": 1,
  "points d'extrémité de l'api": {
    "unités d'organisation":"http://{host}/api/users/rWLrZL8rP3K/organisationUnits/gist?absoluteUrls=true",
    "groupes d'utilisateurs": http://{host}/api/users/rWLrZL8rP3K/userGroups/gist?absoluteUrls=true"
  }
}

Le Champ accès¶

Le résumé accès est basé sur le partage et l'utilisateur actuel. Cela signifie qu'il n'est applicable qu'aux objets ayant une propriété partage.

Par exemple, lors de l'établissement d'une liste d'éléments de données avec le champ accès

/api/dataElements/gist?fields=*,access

les éléments de données renvoyés contiennent un membre "accès" comme ci-dessous :

"accès": {
  "gérer": faux,
  "externaliser": faux,
  "modifier": faux,
  "lire": vrai,
  "mettre à jour": faux,
  "supprimer": faux
}

Attributs comme Champs¶

DHIS2 permet de créer et d'ajouter des attributs personnalisés aux objets de métadonnées. Leurs valeurs sont contenues dans la propriété valeurs d'attributs d'un objet de métadonnées sous la forme d'une carte dont la clé est l'UID de l'attribut.

Pour lister directement une ou plusieurs valeurs d'attributs spécifiques de cette carte comme s'il s'agissait de champs habituels de l'objet de métadonnées, l'UID de l'attribut peut être utilisé comme s'il s'agissait du nom d'un champ habituel.

Par exemple, pour inclure la valeur de l'attribut avec l'UID Y1LUDU8sWBR en tant que la propriété unité de mesure dans la liste, utilisez :

/api/dataElements/gist?fields=id,name,Y1LUDU8sWBR::rename(unit-of-measure)

Il en résulte des éléments de liste du type:

{
  "identifiant": "qrur9Dvnyt5",
  "nom": "Âge en années",
  "unité de mesure" : "années"
}

Par défaut, les valeurs sont récupérées au format JSON et extraites de la carte des valeurs d'attributs. Cela signifie que la liste contiendra le type JSON approprié pour le type de valeur d'attribut. Cela implique un surcoût lié à la récupération de toutes les valeurs d'attributs. Pour isoler la valeur dans la base de données, la transformation PLUCK peut être utilisée.

/api/dataElements/gist?fields=id,name,Y1LUDU8sWBR::rename(unit-of-measure)~pluck

Le résultat sera le même, mais la valeur est désormais extraite sous forme de texte dans la base de données, ce qui transforme toute valeur JSON en une chaîne de caractères dans le résultat de la propriété.

Exemples¶

Quelques exemples partant de simples listes et allant jusqu'à des cas d'utilisation très spécifiques.

Il est préférable de toujours fournir une liste explicite de champs pour que cette section le fasse.

Liste des unités d'organisation avec leur identifiant et leur nom :

/api/organisationUnits/gist?fields=id,name

Liste des unités d'organisation avec leur identifiant, leur nom et leur nombre total :

/api/organisationUnits/gist?fields=id,name&total=true

Liste des utilisateurs avec l'identifiant et le nom d'utilisateur :

/api/users/gist?fields=id,userCredentials.username

Liste des utilisateurs avec l'identifiant, le nom d'utilisateur et la date de la dernière connexion :

/api/users/gist?fields=id,userCredentials[username,lastLogin]

Ne listez que les unités d'organisation au deuxième niveau avec l'identifiant, le nom et le niveau :

/api/organisationUnits/gist?fields=id,name,level&filter=level:eq:2

Listez uniquement les unités d'organisation qui ont plus d'1 enfant avec l'identifiant, le nom et le nombre d'enfants :

/api/organisationUnits/gist?fields=id,name,children::size&filter=children:gt:1

Listez uniquement les unités d'organisation qui ne sont pas encore enfants d'une autre unité zFDYIgyGmXG :

/api/organisationUnits/zFDYIgyGmXG/children/gist?fields=id,name&inverse=true

Listez les utilisateurs et indiquez s'ils sont membres d'un groupe d'utilisateurs spécifique. NTC8Gj7p8P et nommer ce champ est-membre dans la réponse :

/api/users/gist?fields=id,userCredentials.username,userGroups::member(NTC8GjJ7p8P)~rename(is-member)

Listez les liens vers tous les utilisateurs dans des pages de 10 éléments :

/api/users/gist?fields=href&absoluteUrls&pageSize=10