Aller au contenu principal

Utilisation des API

Les API de l'IAM ont un comportement commun:

Organisation et espace​

  • Les API qui fonctionnent sur le perimètre d'une organisation ou d'un espace: La présence des termes spaces ou organisation dans l'URL permet de distinguer la portée des requêtes.

L'URL pour agir au niveau de l'organisation est de la forme: ...iam/organisations/"organisationId"/

Celle pour agir sur un espace est de la forme: ..iam/spaces/"spaceId"/

Le token d'accès​

  • Les API ont besoin d'avoir un token d'accès valide pour fonctionner.

Il est de la forme bearer (lien vers la RFC 6750 The OAuth 2.0 Authorization Framework: Bearer Token Usage. )

Exemple de demande de token
export REGION="myregion"
curl -X POST https://api.$REGION.numspot.cloud/iam/token 
-H 'Accept: */*' 
-H 'Authorization: Basic <base64([Id:secret])>'
-H 'Content-Length: 57' 
-H 'Content-Type: application/x-www-form-urlencoded' 
-d 'grant_type=client_credentials&scope=openid+offline_access'

Une fois que le token est renvoyé, il sera ajouté aux autres demandes sous cette forme:

Ajout d'un token d'accès dans l'entête d'une requête Curl

curl  ... -H "Authorization: Bearer {token}"

La pagination pour les listes​

Les requêtes qui peuvent retourner un nombre indéterminé d'élement disposent d'une pagination.

Il est recommandé d'utiliser la pagination afin d'éviter une trop forte sollicitation du système.

La pagination se présente sous la forme suivante:

  • Par defaut la page est limitée à 30 éléments
  • Le paramètre page[size] renseigne le nombre d'éléments par page.
  • Le paramètre page[nextToken] est renvoyé dans la réponse et est à ajouter à la requête suivante.
  • Des informations pour obtenir la page suivante sont indiquées dans la reponse de la première page
Exemple de requête d'une liste avec pagination
        page[size]=30&page[nextToken]=bee04e3c-850f-4f25-8597-04ba43b24877
   (format encodé: /organisations?page%5BnextToken%5D=bee04e3c-850f-4f25-8597-04ba43b24877)

Le premier nextToken peut prendre n'importe quelle valeur.

Le corps de la réponse contiendra un token à fournir pour avoir la suite:

Exemple de réponse
..'nextPageToken': '287ccb59-0c94-4c90-9798-02c9179f5a3f'

Ce token sera à ajouter comme paramètre à la deuxième requête. Si une troisième page est nécessaire, la deuxième page fournira un nouveau token de page.

'nextPageToken=287ccb59-0c94-4c90-9798-02c9179f5a3f'

#ligne complete
https://...?page%5Bsize%5D=30&page%5BnextToken%5D=bee04e3c-850f-4f25-8597-04ba43b24877

La dernière page ne contiendra pas ce token.

Conventions​

Les URLs des exemples sont parfois présentées avec des termes entre accolades: {organisationId} , {userId} etc. Ces expressions sont à remplacer par les identifiants des entités manipulées.

Les identifiants sont sous la forme UUID (voir RFC 4122)

Traitements asynchrones​

  • La création d'un espace peut prendre plusieurs minutes. L'interrogation d'un espace retournera une clé "status" contenant l'état de l'espace: Le statut peut prendre quatre valeurs:
  • QUEUED
  • RUNNING
  • READY
  • FAILED

L'état nominal d'un espace est READY. Il faut donc attendre sa création complète avant de lancer d'autres opérations.

Correpondance des identifiants​

Toutes les entités manipulées sont identifiées par un UUID. Les API fonctionnent à partir de ces UUID. Aussi pour obtenir le nom correspondant,il est nécessaire de passer par l'API de récupération d'informations de l'ACL. (exemple: retrouver les informations d'un espace ou d'un utilisateur par son identifiant etc. )