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 dimensions constitutives 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

Vous pouvez vérifier et obtenir des informations sur l'utilisateur actuellement authentifié en envoyant une requête GET à l'URL suivante :

/api/33/me

Et plus d'informations sur les autorisations (et si un utilisateur a une certaine autorisation) en utilisant les points d'extrémité :

/api/33/me/authorities
/api/33/me/authorities/ALL

L'authentification de base¶

L'API Web DHIS2 prend en charge l'authentification de base. L'authentification de base est une technique permettant 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 Autorisation. De manière plus formelle, il s'agit de :

Autorisation : 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. Considérez qu'il s'agit d'une exigence impérative pour assurer 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.

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. Création d'un jeton sur la page du compte¶

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. Contexte serveur/script:¶

"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. Contexte navigateur:¶

"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.

Les différents types de contraintes sont les suivants:¶

• 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.

Adresses IP autorisées¶

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.

Méthodes HTTP autorisées¶

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.

Référents HTTP autorisées¶

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.

Sauvegarder votre jeton:¶

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

B. Créer un jeton via l'API¶

Exemple de création d'un nouveau jeton d'accès personnel avec l'API :

POST https://play.dhis2.org/dev/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": []
  }
}

Important : La clé symbolique n'apparaît qu'une seule fois dans cette réponse. Vous devez la copier et l'enregistrer dans un endroit sûr pour pouvoir l'utiliser ultérieurement !

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.

Configurez votre jeton via l'API:¶

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

NB: Seules les contraintes peuvent être modifiées après la création du jeton !

PUT https://play.dhis2.org/dev/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"]
      }
  ]
}

Utiliser votre jeton d'accès personnel¶

Pour envoyer un requête avec votre jeton nouvellement créé, utilisez convenablement l'en-tête d'autorisation . Le format de l'en-tête d'autorisation est le suivant :

Autorisation : ApiToken [YOUR_SECRET_API_TOKEN_KEY]

GET https://play.dhis2.org/dev/api/apiToken/jJYrtIVP7qU
Content-Type: application/json
Authorization: ApiToken d2pat_5xVA12xyUbWNedQxy4ohH77WlxRGVvZZ1151814092

Supprimer votre jeton d'accès personnel¶

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 https://play.dhis2.org/dev/api/apiToken/jJYrtIVP7qU
Content-Type: application/json
Authorization: ApiToken d2pat_5xVA12xyUbWNedQxy4ohH77WlxRGVvZZ1151814092

OAuth2¶

DHIS2 supporte 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 jeton porteur réutilisable pour les demandes 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 de l'utilisateur DHIS2.

Chaque client pour lequel vous souhaitez 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 de subventions.

Ajouter un client à l'aide de l'API Web¶

Un client OAuth2 peut être ajouté via l'API Web. Par exemple, nous pouvons envoyer une charge utile 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"

Nous utiliserons ce client comme base pour nos prochains exemples de types d'octroi.

Mot de passe du type d'octroi¶

Le type d'octroi le plus simple est le type d'octroi mot de passe. Ce type d'octroi 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). A 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'octroi rafraîchir_jeton¶

En général, les jetons d'accès ont une validité limitée. Vous pouvez jeter un coup d'oeil à la propriété expires_in ( expire en) 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 faire un autre aller-retour vers 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 de subvention code_d'autorisation¶

Le type de subvention « code autorisé » est l'approche recommandée si vous ne souhaitez pas stocker les informations d'identification de l'utilisateur en externe. Elle permet au 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. Veuillez noter que cette approche utilise la partie redirectUris de la charge utile 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 de l'octroi du 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¶

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

aaaa-MM-jj

Par exemple, si vous voulez exprimer le 20 mars 2014, vous devez utiliser 2014-03-20.

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

Tableau : Format de la période

Périodes relatives¶

Dans certaines parties de l'API, comme pour la ressource analytique, vous pouvez utiliser des périodes relatives en plus des périodes fixes (définies ci-dessus). Les périodes relatives sont relatives à la date actuelle et permettent, par exemple, de créer des rapports dynamiques. Les valeurs disponibles pour les périodes relatives sont les suivantes :

THIS_WEEK, LAST_WEEK, LAST_4_WEEKS, LAST_12_WEEKS, LAST_52_WEEKS,
THIS_BIWEEK, LAST_BIWEEK, LAST_4_BIWEEKS,
THIS_MONTH, LAST_MONTH, THIS_BIMONTH, LAST_BIMONTH, THIS_QUARTER, LAST_QUARTER,
THIS_SIX_MONTH, LAST_SIX_MONTH, MONTHS_THIS_YEAR, QUARTERS_THIS_YEAR,
THIS_YEAR, MONTHS_LAST_YEAR, QUARTERS_LAST_YEAR, LAST_YEAR, LAST_5_YEARS, LAST_10_YEARS, LAST_10_FINANCIAL_YEARS, LAST_12_MONTHS, 
LAST_3_MONTHS, LAST_6_BIMONTHS, LAST_4_QUARTERS, LAST_2_SIXMONTHS, THIS_FINANCIAL_YEAR,
LAST_FINANCIAL_YEAR, LAST_5_FINANCIAL_YEARS

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.

Les conditions peuvent être exprimées sous la forme suivante :

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

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

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

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

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 :

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

Autorités¶

Les identifiants et les noms des autorités du système peuvent être répertoriés à l'aide de la fonction :

/api/authorities

Il renvoie le format suivant :

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