Aperçu¶

L'API Web est un composant qui permet aux systèmes externes d'accéder aux données stockées dans une instance DHIS2 et de les manipuler. Plus précisément, elle fournit une interface programmatique à un large éventail de données exposées et de méthodes de service pour des applications telles que des clients logiciels tiers, des portails web et des modules DHIS2 internes.

Introduction¶

L'API Web adhère à de nombreux principes du style architectural REST. Pour n'en citer que certains, importants :

1. Les éléments fondamentaux sont appelés ressources. Une ressource peut être tout ce qui est exposé sur le web, d'un document à un processus d'entreprise - tout ce avec quoi un client peut vouloir interagir. Les aspects informatifs d'une ressource peuvent être récupérés ou échangés par le biais de représentations de la ressource. Une représentation est une vue de l'état d'une ressource à un moment donné. Par exemple, la ressource visualisations dans DHIS2 représente des visualisations de données agrégées pour un certain ensemble de paramètres. Cette ressource peut être récupérée dans divers formats de représentation, notamment JSON et CSV.
2. Toutes les ressources peuvent être identifiées de manière unique par un URI (également appelé URL). Toutes les ressources ont une représentation par défaut. Vous pouvez indiquer que vous êtes intéressé par une représentation spécifique en fournissant un en-tête HTTP Accept, une extension de fichier ou un paramètre de requête format. Ainsi, pour récupérer une représentation CSV d'une réponse de données analytiques, vous pouvez fournir un en-tête Accept : application/csv ou ajouter .csv ou ?format=csv à l'URL de votre requête.
3. Les interactions avec l'API nécessitent l'utilisation correcte des méthodes ou verbes HTTP. Cela implique que pour une ressource, vous devez émettre une requête GET lorsque vous souhaitez la récupérer, une requête POST lorsque vous souhaitez en créer une, une requête PUT lorsque vous souhaitez la mettre à jour et une requête DELETE lorsque vous souhaitez la supprimer.

Authentification¶

L'API Web DHIS2 prend en charge trois protocoles d'authentification :

• L'authentification de base
• Les jetons d'accès personnels (PAT)
• OAuth 2

Verify and get information about the currently authenticated user by making a GET request to the following endpoint.

GET /api/me

Get the list of authorities for the currently authenticatd user.

GET /api/me/authorization

Check whether the currently authenticated user has the given authority.

GET /api/me/authorization/{authority}

For example, to check whether the user has the F_CONSTANT_ADD authority.

GET /api/me/authorization/F_CONSTANT_ADD

The response will be either true or false in JSON format.

Authentification de base¶

L'API Web DHIS2 prend en charge l'authentification de base. L'authentification de base est une technique qui permet aux clients d'envoyer des informations d'identification par HTTP à un serveur web. Techniquement parlant, le nom d'utilisateur est suivi de deux points et le mot de passe, encodé en Base64, est préfixé par Basic et fourni en tant que valeur de l'en-tête HTTP Authorization (autorisation). De manière plus formelle, il s'agit de :

Authorization: Basic base64encode(nom d'utilisateur:mot de passe)

La plupart des environnements de développement compatibles avec les réseaux prennent en charge l'authentification de base, comme Apache HttpClient et Spring RestTemplate. Il est important de noter que ce schéma d'authentification n'offre aucune sécurité puisque le nom d'utilisateur et le mot de passe sont envoyés en texte clair et peuvent être facilement observés par un pirate. L'utilisation de Basic n'est recommandée que si le serveur utilise SSL/TLS (HTTPS) pour crypter la communication avec les clients. Ceci est un impératif, afin de garantir des interactions sécurisées avec l'API Web.

Authentification à deux facteurs¶

DHIS2 prend en charge l'authentification à deux facteurs. Cette fonction peut être activée pour chaque utilisateur. Lorsque cette option est activée, les utilisateurs sont invités à saisir un code 2FA lorsqu'ils se connectent. Pour en savoir plus sur l'authentification à deux facteurs, cliquez [ici] (https://www.google.com/landing/2step/).

Jeton d'accès personnel¶

Les jetons d'accès personnels (PAT) sont une alternative à l'utilisation de mots de passe lors de l'authentification au système DHIS2 lorsque l'on utilise l'API.

Les jetons d'accès personnel peuvent être une alternative plus sécurisée à l'authentification de base HTTP et devraient être votre choix privilégié lorsque vous créez une nouvelle application, un script, etc.

L'authentification de base HTTP est considérée comme non sécurisée car, entre autres, elle envoie votre nom d'utilisateur et votre mot de passe de façon indiscrète. Il est possible qu'elle soit abandonnée dans les versions futures de DHIS2 ou qu'elle devienne facultative, ce qui signifie que l'authentification de base devra être explicitement activée dans la configuration.

Problèmes de sécurité majeurs !¶

Vos jetons d'accès personnel hériteront automatiquement de toutes les permissions et autorisations dont dispose votre utilisateur. Il est donc extrêmement important de limiter l'accès que vous accordez à votre jeton en fonction de l'utilisation que vous comptez en faire, voir Configurer votre jeton.

Si vous souhaitez que le jeton n'ait accès qu'à une partie restreinte et spécifique du serveur, il est plutôt recommandé de créer un nouvel utilisateur spécial auquel vous n'attribuerez que les rôles et autorisations auxquels vous souhaitez qu'il ait accès.

Création d'un jeton¶

Pour créer un nouveau PAT, vous avez deux possibilités : * A. Créez un jeton dans l'interface utilisateur de la page de profil de votre compte. * B. Créer un jeton via l'API.

A. Creating a token on the account page¶

Connectez-vous avec votre nom d'utilisateur et votre mot de passe, allez sur votre page de profil (cliquez en haut à droite, et choisissez « Modifier le profil » dans le menu déroulant). Sur votre page de profil, choisissez « Jetons d'accès personnels » dans le menu à gauche. Vous devriez maintenant être sur la page « Gérer les jetons d'accès personnels » et voir le texte : « Vous n'avez pas de jetons d'accès personnels actifs ». Cliquez sur « Générer un nouveau jeton » pour créer un nouveau jeton. Une fenêtre contextuelle « Générer un nouveau jeton » s'affiche et vous propose deux choix :

1. Server/script context¶

"Ce type est utilisé pour les intégrations et les scripts qui ne seront pas accessibles par un navigateur".

Si vous prévoyez d'utiliser le jeton dans une application, un script ou autre, ce type de jeton devrait être votre choix.

2. Browser context¶

"Ce type d'application est utilisé pour les applications, telles que les portails publics, auxquelles on accède à l'aide d'un navigateur web".

Si vous devez créer un lien vers DHIS2 sur une page web, ou par exemple l'intégrer dans une iframe, c'est probablement le type de jeton qu'il vous faut.

Configuration de votre jeton¶

Après avoir choisi le type de jeton que vous désirez, vous pouvez configurer différentes contraintes d'accès à votre jeton. Par contrainte, nous entendons la manière de limiter et de restreindre l'utilisation de votre jeton. Cela peut être d'une importance cruciale si vous envisagez d'utiliser le jeton dans un environnement public, par exemple sur un tableau de bord public d'un autre site, intégré dans une iframe. Étant donné que les jetons ont toujours les mêmes accès/autorisations que ceux dont dispose actuellement votre utilisateur, il convient d'être particulièrement vigilant si vous avez l'intention de les utiliser dans un environnement que vous ne contrôlez pas à 100 %.

NB : Si quelqu'un d'autre met la main sur votre jeton, il peut faire tout ce que votre utilisateur est capable de faire. Il n'est pas possible de faire la distinction entre les actions effectuées à l'aide du jeton et les autres actions effectuées par votre utilisateur.

Important : Il est fortement conseillé de créer un utilisateur distinct et unique ayant uniquement les rôles/autorisations si vous envisagez d'utiliser les jetons PAT dans un environnement non sécurisé et/ou public, par exemple, sur un PC ou un serveur que vous ne contrôlez pas à 100 %, ou « intégré » dans une page web sur un autre serveur.

Constraint types¶

• Temps d'expiration
• Adresses UP autorisées
• Méthodes HTTP autorisées
• Référents HTTP autorisés

Temps d'expiration¶

La durée d'expiration définit simplement la durée pendant laquelle vous souhaitez que votre jeton soit utilisable, le délai par défaut étant de 30 jours. Passé ce délai, le jeton renverra simplement un message 401 (non autorisé). Vous pouvez définir le délai d'expiration que vous souhaitez, mais il est fortement conseillé de définir un délai d'expiration raisonnable pour votre cas d'utilisation.

IP addresses¶

Il s'agit d'une liste d'adresses IP séparées par des virgules, à partir desquelles vous souhaitez limiter la provenance des requêtes de jetons.

Important: La validation de l'adresse IP repose sur l'en-tête X-Transféré-À, qui peut être usurpé. Pour des raisons de sécurité, assurez-vous qu'un équilibreur de charge ou un proxy inverse écrase cet en-tête.

HTTP methods¶

Une liste de méthodes HTTP séparées par des virgules que vous souhaitez que votre jeton puisse utiliser. Si vous n'avez besoin de votre jeton que pour consulter des données, et non pour les modifier ou les supprimer, la sélection de la méthode GET HTTP est judicieuse.

HTTP referrers¶

Le référent HTTP est un en-tête ajouté à la requête lorsque vous cliquez sur un lien, il indique le site/la page sur lequel/laquelle vous étiez lorsque vous avez cliqué sur le lien. Pour en savoir plus sur l'en-tête du référent HTTP, cliquez sur le lien suivant : https://en.wikipedia.org/wiki/HTTP_referer

Cela peut servir à limiter l'utilisation d'un jeton « public » intégré à une autre page sur un autre site. S'assurer que l'en-tête du référent correspond au nom d'hôte du site d'où le jeton doit provenir peut éviter l'utilisation abusive du jeton, par exemple si quelqu'un le publie sur un forum public.

Important Ceci n'est pas une fonctionnalité de sécurité. L'en-tête référence peut être facilement usurpé. Ce paramètre est destiné à dissuader les développeurs tiers non autorisés à se connecter aux instances d'accès public.

Saving a token¶

Lorsque vous avez fini de configurer votre jeton, vous pouvez l'enregistrer en cliquant sur le bouton « Générer un nouveau jeton » en bas à droite de la fenêtre contextuelle. Le jeton sera alors sauvegardé et une clé secrète sera générée sur le serveur. La nouvelle clé secrète sera affichée en bas de la liste des jetons PAT sur fond vert, et le texte « Jeton nouvellement créé ». La clé du jeton secret ressemble à ceci :

d2pat_5xVA12xyUbWNedQxy4ohH77WlxRGVvZZ1151814092

Creating a token with the API¶

Example of how to create a new Personal Access Token using the API:

POST /api/apiToken
Content-Type: application/json
Authorization: Basic admin district

{}

Il renverra une réponse contenant un jeton similaire à celui-ci :

{
  "httpStatus": "Created",
  "httpStatusCode": 201,
  "status": "OK",
  "response": {
     "responseType": "ApiTokenCreationResponse",
     "key": "d2pat_5xVA12xyUbWNedQxy4ohH77WlxRGVvZZ1151814092",
     "uid": "jJYrtIVP7qU",
     "klass": "org.hisp.dhis.security.apikey.ApiToken",
     "errorReports": []
  }
}

Note: The token key will only be shown once here in this response. You need to copy and save this is in a secure place for use later!

Le jeton lui-même se compose de trois parties : 1. Préfixe : (d2pat_) indique de quel type de jeton il s'agit. 2. Octets aléatoires codés en Base64: (5xVA12xyUbWNedQxy4ohH77WlxRGVvZZ) 3. Somme de contrôle CRC32 : (1151814092) la partie de la somme de contrôle est complétée par 0 de sorte qu'elle conserve toujours une longueur de dix caractères.

Configure token with the API¶

Pour modifier l'une des contraintes de votre jeton, vous pouvez envoyer la requête API HTTP suivante.

Note: Only the constraints are possible to modify after the token has been created.

PUT /api/apiToken/jJYrtIVP7qU
Content-Type: application/json
Authorization: Basic admin district

{
  "version": 1,
  "type": "PERSONAL_ACCESS_TOKEN",
  "expire": 163465349603200,
  "attributes": [
      {
        "type": "IpAllowedList",
        "allowedIps": ["192.168.0.1"]
      },
      {
        "type": "MethodAllowedList",
        "allowedMethods": ["GET"]
      }
  ]
}

Using a Personal Access Token¶

To issue a request with your newly created token, use the Authorization header accordingly. The authorization header format is:

Autorisation : ApiToken [YOUR_SECRET_API_TOKEN_KEY]

Par exemple :

GET /api/apiToken/jJYrtIVP7qU
Content-Type: application/json
Authorization: ApiToken d2pat_5xVA12xyUbWNedQxy4ohH77WlxRGVvZZ1151814092

Deleting a Personal Access Token¶

Vous pouvez supprimer vos PAT soit dans l'interface utilisateur de votre page de profil où vous les avez créés, soit via l'API comme ceci :

DELETE /api/apiToken/jJYrtIVP7qU
Content-Type: application/json
Authorization: ApiToken d2pat_5xVA12xyUbWNedQxy4ohH77WlxRGVvZZ1151814092

OAuth2¶

DHIS2 prend en charge le protocole d'authentification OAuth2. OAuth2 est une norme ouverte d'autorisation qui permet aux clients tiers de se connecter au nom d'un utilisateur DHIS2 et d'obtenir un bearer token (jeton porteur) réutilisable pour les requêtes ultérieures à l'API Web. DHIS2 ne prend pas en charge les rôles OAuth2 à granularité fine, mais fournit aux applications un accès basé sur les rôles d'utilisateur de DHIS2.

Chaque client pour lequel vous voulez autoriser l'authentification OAuth 2 doit être enregistré dans DHIS2. Pour ajouter un nouveau client OAuth2, allez dans Applications > Paramètres > Clients OAuth2 dans l'interface utilisateur, cliquez sur Ajouter nouveau et entrez le nom du client souhaité et les types d'autorisations.

Create a Client¶

Un client OAuth2 peut être ajouté via l'API Web. Par exemple, nous pouvons envoyer une charge comme celle-ci :

{
  "name": "OAuth2 Demo Client",
  "cid": "demo",
  "secret": "1e6db50c-0fee-11e5-98d0-3c15c2c6caf6",
  "grantTypes": [
    "password",
    "refresh_token",
    "authorization_code"
  ],
  "redirectUris": [
    "http://www.example.org"
  ]
}

La charge utile peut être envoyée avec la commande suivante :

SERVER="https://play.dhis2.org/dev"
curl -X POST -H "Content-Type: application/json" -d @client.json
  -u admin:district "$SERVER/api/oAuth2Clients"

This client will be used as the basis for the next grant type examples.

Type d'autorisation "Mot de passe"¶

Le type d'autorisation le plus simple est le type mot de passe. Ce type d'autorisation est similaire à l'authentification de base en ce sens qu'il exige du client qu'il recueille le nom d'utilisateur et le mot de passe de l'utilisateur. Prenons l'exemple de notre serveur de démonstration :

SERVER="https://play.dhis2.org/dev"
SECRET="1e6db50c-0fee-11e5-98d0-3c15c2c6caf6"

curl -X POST -H "Accept: application/json" -u demo:$SECRET "$SERVER/uaa/oauth/token"
  -d grant_type=password -d username=admin -d password=district

Vous obtiendrez une réponse similaire à ceci :

{
  "expires_in": 43175,
  "scope": "ALL",
  "access_token": "07fc551c-806c-41a4-9a8c-10658bd15435",
  "refresh_token": "a4e4de45-4743-481d-9345-2cfe34732fcc",
  "token_type": "bearer"
}

Pour l'instant, nous allons nous concentrer sur le access_token, qui sera utilisé comme jeton d'authentification (porteur). À titre d'exemple, nous allons obtenir tous les éléments de données en utilisant notre jeton :

SERVER="https://play.dhis2.org/dev"
curl -H "Authorization: Bearer 07fc551c-806c-41a4-9a8c-10658bd15435" "$SERVER/api/33/dataElements.json"

Type d'autorisation "rafraîchir_jeton"{ #webapi_refresh_token }¶

En général, les jetons d'accès ont une validité limitée. Vous pouvez jeter un coup d'œil à la propriété expires_in (expire dans) de la réponse dans l'exemple précédent pour comprendre quand un jeton expire. Pour obtenir un nouveau access_token (jeton d'accès), vous pouvez visiter le serveur et utiliser refresh_token (rafraîchir le jeton) qui vous permet d'obtenir un jeton mis à jour sans avoir besoin de demander les informations d'identification de l'utilisateur une fois de plus.

SERVER="https://play.dhis2.org/dev"
SECRET="1e6db50c-0fee-11e5-98d0-3c15c2c6caf6"
REFRESH_TOKEN="a4e4de45-4743-481d-9345-2cfe34732fcc"

curl -X POST -H "Accept: application/json" -u demo:$SECRET "$SERVER/uaa/oauth/token"
  -d "grant_type=refresh_token" -d "refresh_token=$REFRESH_TOKEN"

La réponse sera exactement la même que lorsque vous obtenez un jeton au départ.

Type d'autorisation "code_d'autorisation"¶

Le type "code autorisé" est l'approche recommandée si vous ne voulez pas stocker les informations d'identification de l'utilisateur en externe. Elle permet à DHIS2 de collecter le nom d'utilisateur et le mot de passe directement auprès de l'utilisateur au lieu que le client les collecte et s'authentifie ensuite au nom de l'utilisateur. Notez que cette approche utilise la partie redirectUris de la charge du client.

Étape 1 : Visitez l'URL suivante à l'aide d'un navigateur web. Si vous avez plus d'un URI de redirection, vous pouvez ajouter &redirect_uri=http://www.example.org à l'URL :

SERVER="https://play.dhis2.org/dev"
$SERVER/uaa/oauth/authorize?client_id=demo&response_type=code

Étape 2 : Une fois que l'utilisateur s'est connecté avec succès et a accepté votre accès client, il sera redirigé vers votre uri de redirection comme suit :

http://www.example.org/?code=XYZ

Étape 3 : Cette étape est similaire à celle du type d'autorisation "mot de passe". En utilisant le code fourni, nous allons maintenant demander un jeton d'accès :

SERVER="https://play.dhis2.org/dev"
SECRET="1e6db50c-0fee-11e5-98d0-3c15c2c6caf6"

curl -X POST -u demo:$SECRET -H "Accept: application/json" $SERVER/uaa/oauth/token
-d "grant_type=authorization_code" -d "code=XYZ"

Messages d'erreur et d'information¶

L'API Web utilise un format cohérent pour tous les messages d'erreur, d'avertissement et d'information :

{
  "httpStatus": "Forbidden",
  "message": "Vous n'avez pas la permission de lire ce type d'objet.",
  "httpStatusCode": 403,
  "status": "ERROR"
}

Le message indique que l'utilisateur a essayé d'accéder à une ressource à laquelle je n'ai pas accès. Il utilise le code de statut http 403, le message de statut http interdit et un message descriptif.

Tableau : Propriétés de WebMessage

Format de la date et de la période¶

Dans l'API Web, nous faisons référence à des dates et à des périodes. Le format de la date est le suivant :

yyyy-MM-dd

For example, if you want to express March 20, 2014, you must use 2014-03-20.

Le format de la période est décrit dans le tableau suivant (également disponible dans le endpoint de l'API /api/periodTypes)

Tableau : Format de la période

Périodes relatives¶

In some parts of the API, like for the analytics resource, you can utilize relative periods in addition to fixed periods (defined above). The relative periods are relative to the current date and allow e.g. for creating dynamic reports. The available relative period values are described in the table below.

It is possible retrieve the ISO representations of these relative periods by making a GET request to the /api/relativePeriods/{RELATIVE_PERIOD_KEYWORD}

The endpoint supports the following parameters: - startDate: Represents the start date to calculate the relative period from. Format: yyyy-MM-dd. Default is today if not provided. - financialYearStart: Should be one of FINANCIAL_YEAR_FEBRUARY, FINANCIAL_YEAR_APRIL, FINANCIAL_YEAR_JULY, FINANCIAL_YEAR_AUGUST, FINANCIAL_YEAR_SEPTEMBER, FINANCIAL_YEAR_OCTOBER. Default is FINANCIAL_YEAR_OCTOBER if not provided.

As an example, to get the ISO representation of the relative period LAST_3_MONTHS from the date 2021-08-15, you can issue the following request: GET /api/relativePeriods/LAST_3_MONTHS?startDate=2021-08-15

The response in this case would be:

{
[
"202105",
"202106",
"202107"
]
}

Périodes de dates personnalisées¶

Les ressources analytiques query supportent des paramètres supplémentaires pour exprimer des périodes.

La dimension pe par défaut sera utilisée :

• eventDate pour /analytics/events/query
• enrollmentDate pour /analytics/enrollments/query

Il est possible d'ajouter des conditions sur un ou plusieurs champs de date et de les combiner.

Utilisation de périodes de dates personnalisées¶

Dans les ressources prenant en charge des périodes de dates personnalisées, il existe des paramètres de requête supplémentaires qui seront combinés pour exprimer des conditions sur la dimension temporelle.

Conditions can be expressed in the following format:

/api/analytics/events/query/...?...&eventDate=2021&...

Il est possible de combiner plusieurs champs temporels dans la même requête :

/api/analytics/events/query/...?...&eventDate=2021&incidentDate=202102&...

Toutes ces conditions peuvent être combinées avec la dimension pe :

/api/analytics/events/query/...?...&dimension=pe:TODAY&enrollmentDate=2021&incidentDate=202102&...

Les formats pris en charge sont décrits dans la section « Format de date et de période » ci-dessus. Un format supplémentaire est fourni pour exprimer un intervalle de dates : aaaaMMjj_aaaaMMjj et aaaa-MM-jj_aaaa-MM-jj.

Dans l'exemple ci-dessous, le point d'extrémité renvoie les événements prévus entre 20210101 et 20210104 :

/api/analytics/events/query/...?...&dimension=pe:TODAY&enrollmentDate=2021&incidentDate=202102&scheduledDate=20210101_20210104&...

Autorités¶

All available system authorities can be listed with identifiers and names using the following endpoint.

GET /api/authorities

Il renvoie le format suivant :

{
  "systemAuthorities": [
    {
      "id": "ALL",
      "name": "ALL"
    },
    {
      "id": "F_ACCEPT_DATA_LOWER_LEVELS",
      "name": "Accept data at lower levels"
    }
  ]
}