[Quick start] API Publique DataGalaxy v2

Authentification

Notre API utilise une authentification basée sur des tokens. Chaque requête doit contenir un en-tête Authorization incluant un token d’accès.

Utilisez soit un token d’intégration DataGalaxy, soit un token d’accès personnel comme jeton pour vos appels API. Dans cet exemple, nous allons créer un token d’intégration. Un token d’intégration est valable pour l’ensemble de l’environnement DataGalaxy et ne dépend pas des droits d’accès d’un utilisateur spécifique.

Création d'un token d'intégration

Commencez par vous connecter à votre instance DataGalaxy avec un compte administrateur de l’espace client. Ensuite, accédez à la page d’administration en cliquant sur votre menu profil en haut à droite de la page, puis sur le lien « Administration ».

Naviguez ensuite vers la page d'intégration où vous pourrez créer votre token d'intégration ou utiliser un existant.

- Cliquez sur le bouton « + Créer » pour ouvrir une fenêtre de création d’un nouveau token d’intégration.

- Saisissez un nom explicite afin de pouvoir l’identifier facilement par la suite.

- Si vous prévoyez d’utiliser l’API pour créer des utilisateurs, mettre à jour des utilisateurs ou modifier des licences, cochez l’option « Accès administrateur ».

- Cliquez sur « Enregistrer » pour créer le token d’intégration.

- Utilisez la valeur de ce token dans l’en-tête Authorization de vos appels API.

URL de base de l'API

Chaque environnement DataGalaxy dispose d’une URL de base spécifique pour l’API.
L’URL de base correspond au nom d’hôte et au chemin racine des requêtes effectuées via l’API.
Vous pouvez retrouver l’URL de base de votre environnement depuis la page API DataGalaxy dans le portail.

Cliquez sur votre menu profil en haut à droite de la page, puis sur le lien « API DataGalaxy » pour ouvrir une fenêtre contenant plus d’informations sur l’API.
L’URL de base de l’API est affichée au centre de cette fenêtre.

Exemple : Créer un objet source

Avec un token d’accès, vous êtes désormais en mesure de gérer vos entités DataGalaxy.

L’exemple suivant décrit le workflow permettant de créer un objet source dans votre espace de travail par défaut.

Un objet source possède plusieurs dépendances, et ces dépendances peuvent être récupérées via l’API DataGalaxy.

Notre workflow comprend les étapes suivantes :

1. Appeler la route GET /v2/workspaces pour récupérer les identifiants de votre workspace et de la version du workspace

2. Appeler la route GET /v2/users pour récupérer les adresses email des utilisateurs owner et steward

3. Appeler la route GET /v2/tags pour récupérer les tags valides à associer au nouvel objet source

4. Appeler la route POST /v2/sources pour créer l’objet source

Veuillez noter que les exemples de code ci-dessous utilisent l’utilitaire HTTP en ligne de commande curl.

Les réponses de l’API sont formatées ici pour en faciliter la lecture, mais les réponses réelles de l’API sont des contenus JSON sur une seule ligne.

Étape 1 : récupérer les workspaces

Tous les objets DataGalaxy sont associés à un workspace. Commencez par récupérer vos workspaces.

Les identifiants de workspace et de version de workspace sont des chaînes UUIDv4.

$ curl --header 'Authorization: Bearer <access token>' \
  'https://<API base URL>/workspaces'

{
  "organizations": [],
  "projects": [
    {
      "defaultVersionName": "v1",
      "defaultVersionId": "<version ID>",
      "isVersioningEnabled": true,
      "description": null,
      "canCreateEntities": true, 
      "id": "<workspace ID>",
      "name": "My Workspace", 
      "parentId": null
    }
  ]
}

Notez l’identifiant de version (version ID) dans la réponse. Utilisez cet ID dans le chemin URL de vos prochaines requêtes afin de cibler la version appropriée du workspace.

Étape 2 : récupérer les utilisateurs

$ curl --header 'Authorization: Bearer <access token>' \
  'https://<API base URL>/users/<version ID>?module=catalog' 

{
  "pages": 1, 
  "total": 17, 
  "results": [ 
    { 
      "userId": "<user ID>",
      "licenseLevel": "Admin",
      "firstName": "John",
      "lastName": "Doe",
      "email": "john.doe@example.com",
      "licenseId": <license ID>,
      "title": null,
      "service": null,
      "role": null
    }, 
    {
      "userId": "<another user ID>",
      "licenseLevel": "Steward",
      "firstName": "Jane",
      "lastName": "Doe",
      "email": "jane.doe@example.com",
      "licenseId": <another user ID>,
      "title": null,
      "service": null,
      "role": null
    }, 
    ...
  ]
}

Notez les adresses email de vos utilisateurs data owner et data steward.
Dans cet exemple, ces adresses sont : "john.doe@example.com" et "jane.doe@example.com".

Étape 3 : récupérer les étiquettes

$ curl --header 'Authorization: Bearer <access token>' \
  'https://<API base URL>/tags' 

{
  "pages": 1,
  "total": 6,
  "results": [
    {
      "name": "GDPR",
      "description": "Data covered by the General Data Protection Regulation"
    },
    {
      "name": "CRM"
    },
    {
      "name": "Marketing"
    },
    ...
  ]
}

{
  "name": "My NoSQL source",
  "type": "NoSql",
  "tags": ["GDPR"],
  "owners": ["john.doe@example.com"],
  "stewards": ["jane.doe@example.com"]
}

$ curl --request POST \
  --header 'Authorization: Bearer <access token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "My NoSQL source",
  "type": "NoSql",
  "tags": ["GDPR"],
  "owners": ["john.doe@example.com"],
  "stewards": ["jane.doe@example.com"]
}' \
  'https://<API base URL>/sources/<version ID>'

{
  "id": "<new source ID>",
  "location": "sources/<version ID>/<new source ID>"
}