L’interface REST « Management »

L’interface REST “Management” (ou Management API) fournit des opérations permettant de configurer la Constellation :

• Gestion des sentinelles
• Gestion des packages
• Gestion des groupes
• Gestion des settings
• Gestion des RecoveryOptions
• Gestion des credentials et autorisations
• Gestion du Package Repository et upload de package
• Gestion de la licence
• Lire / Ecriture du fichier de configuration
• Récupération du numéro de version du serveur
• Rechargement et déploiement de la configuration

Généralités

Construction de l’URL

L’URL est :  <Root URI>/rest/management/<action>?<paramètres>

Partons du principe que votre Constellation est exposée en HTTP sur le port 8088 (sans path). On retrouvera dans le fichier de configuration la section suivante :

La “Root URI “ est donc “http://<ip ou dns>:8088/”.

Par exemple si nous sommes en local, nous pourrions écrire :

Authentification

Comme pour toutes les requêtes vers Constellation vous devez impérativement spécifier dans les headers HTTP ou dans les paramètres de l’URL (querystring), les paramètres “SentinelName”, “PackageName” et “AccessKey” pour l’authentification.

Dans le cas de l’API “Management”, la “SentinelName” est “Management” et le “PackageName” est le nom de votre choix que l’on considère comme un “FriendlyName”. Typiquement le “FriendlyName” est par exemple le nom de l’application/page qui se connecte.

L’AccessKey doit bien sûr être déclaré et activé sur le serveur. De plus elle doit avoir le droit  d’utiliser l’API de Management, soit depuis la Console Constellation ou soit directement dans le fichier de configuration en ajoutant l’attribut “enableManagementAPI”.

Ainsi chaque appel aura le format suivant :

Check Access

Toutes les API REST de Constellation exposent une méthode en GET “CheckAccess” qui retourne un code HTTP 200 (OK). Cela permet de tester la connexion et l’authentification au serveur Constellation.

• Action : “CheckAccess” (GET)
• Paramètres : aucun

Exemple :

Récupérer la version du serveur

Pour connaitre la version du serveur Constellation, vous pouvez invoquer l’action “/server/version”.

• Action : “/server/version” (GET)
• Paramètres : aucun

Exemple :

Edition du fichier de configuration

Lire le fichier de configuration

Vous pouvez récupérer le contenu entier du fichier de configuration de votre Constellation en invoquant l’action ”/configuration”

• Action : “/configuration” (GET)
• Paramètres : aucun

Exemple :

Ecrire le fichier de configuration

Vous pouvez également réécrire le fichier de configuration en postant le nouveau contenu sur la même URL.

• Action : “/configuration” (POST)
• Paramètres : aucun
• Corps de la requête : le fichier de configuration XML

Le serveur vérifiera le bon format du fichier XML avant d’écraser le fichier de configuration existant par votre nouvelle version. Vous devrez ensuite recharger la configuration pour appliquer les modifications.

Recharger et déployer la configuration

Pour recharger le fichier de configuration vous devez invoquer l’action “/configuration/reload” :

• Action : “/configuration/reload ” (GET)
• Paramètres :
  • deployConfiguration (optionnel – par défaut “false”) : indique si l’ordre de mise à jour doit être envoyé aux sentinelles et packages de la Constellation

Exemple :

La License Constellation

Vous pouvez récupérer les caractéristiques de la licence affectée à votre serveur en invoquant l’action  “/license”.

• Action : “/license” (GET)
• Paramètres : aucun

Exemple :

Vous pouvez également charger une nouvelle licence en utilisant le verbe “POST” sur cette action et en plaçant le contenu de la nouvelle licence dans le corps de la requête.

Gestion du Package Repository

Lister le Package Repository

Pour récupérer la liste des packages de le Package Repository :

• Action : “/packages” (GET)
• Paramètres : aucun

Exemple :

Récupérer un package

Pour récupérer un package en particulier de votre Package Repository :

• Action : “/packages/{packageName}” (GET)
• Paramètres : aucun

Exemple :

Renommer un package

Pour renommer un package de votre Package Repository vous devez poster un objet JSON contenant son nouveau nom :

• Action : “/packages/{packageName}” (POST)
• Paramètres : aucun
• Corps de la requête (application/json) : { « newName »: newName }

Supprimer un package

Pour supprimer package de votre Package Repository :

• Action : “/packages/{packageName}” (DELETE)
• Paramètres : aucun

Récupérer l’icone d’un package

Pour récupérer l’icone d’un package de votre Package Repository :

• Action : “/packages/{packageName}/icon” (GET)
• Paramètres : aucun

Vous obtiendrez l’icone au format “PNG”.

Exemple :

Récupérer le schéma XSD d’un paramètre de configuration d’un package

Chaque package peut avoir des settings. Ces settings peuvent être de plusieurs types (types simples, objet JSON ou XML). Chaque package doit (ou devrait) déclarer la liste des settings qu’il utilise dans son “Package Manifest”.

Si le setting est de type XML (“ConfigurationSection” ou “XmlDocument”) il peut être lié à un schéma XSD pour décrire le format XML du setting en question.

L’action ci-dessous permet de récupérer ce schema XSD pour un setting d’un package de votre Package Repository.

• Action : ”/packages/{package}/settings/{settingName}/xsd ” (GET)
• Paramètres : aucun

Exemple :

Télécharger un package vers votre Package Repository

Vous pouvez ordonner à votre serveur Constellation de télécharger un fichier vers le Package Repository.

Pour cela vous utiliserez l’action “/download-package” en spécifiant l’URL du fichier à télécharger.

• • Action : ”/download-package” (POST)
  • Paramètres : aucun
  • Corps de la requête (application/json) : { « url »: url}

Téléverser un package vers votre Package Repository

Vous pouvez également envoyer un fichier vers votre Package Repository en utilisant l’action “/upload-package”.

• Action : ”/upload-package” (POST)
• Paramètres : aucun
• Corps de la requête (multipart/form-data) : les fichiers à enregistrer dans votre Package Repository.

Les RecoveryOptions

Les Recovery Options spécifient les options de récupération en cas de crash d’un package sur vos sentinelles.

Chaque package peut avoir ses propres options mais par défaut il hérite des options “globales”.

Pour récupérer ces options “globales” :

• Action : ”/configuration/recoveryoptions” (GET)
• Paramètres : aucun

Exemple :

Vous pouvez également redéfinir ces options en postant sur cette même URI votre nouvel objet JSON :

• Action : ”/configuration/recoveryoptions” (POST)
• Paramètres : aucun
• Corps de la requête (application/json) : l’objet “RecoveryOptions” avec les nouvelles valeurs

Gestion des sentinelles

Lister les sentinelles

Pour récupérer la liste des sentinelles de votre Constellation :

• Action : “/sentinels” (GET)
• Paramètres : aucun

Exemple :

Ajouter ou modifier une sentinelle

Pour ajouter ou modifier une sentinelle de votre Constellation :

• Action : “/sentinels” (POST)
• Paramètres : aucun
• Corps de la requête (application/json) : un objet JSON contenant deux propriétés :
  • “Name”  : le nom de la sentinelle
  • “Credential” : le nom du credential associé à cette sentinelle

Supprimer une sentinelle

Pour supprimer une sentinelle de votre Constellation :

• Action : “/sentinels/{sentinelName}” (DELETE)
• Paramètres : aucun

Gestion des packages et des settings

Lister les packages d’une sentinelles

Pour récupérer la liste des packages (virtuels ou non) d’une sentinelle (virtuelle ou non) de votre Constellation :

• Action : “/sentinels/{sentinelName}/packages” (GET)
• Paramètres : aucun

Exemple :

Récupérer une instance d’un package

Pour récupérer le détail d’une instance de package sur une sentinelle donnée :

• Action : “/sentinels/{sentinelName}/packages/{packageName}” (GET)
• Paramètres : aucun

Exemple :

Ajouter ou modifier une instance d’un package

Pour ajouter ou modifier un package sur une sentinelle de votre Constellation :

• Action : “/sentinels/{sentinel}/packages” (POST)
• Paramètres : aucun
• Corps de la requête (application/json) : un objet JSON contenant cinq propriétés :
  • “Name”: le nom de l’instance du package (obligatoire et unique)
  • “PackageFile” (facultatif) : le nom du fichier du package à utiliser dans le repository (plus d’info)
  • “Enable” (facultatif, par defaut true) : indique si le package est activé ou désactivé
  • “Credential” (facultatif, utilise par défaut du credential de sa sentinelle) : spécifie le credential que le package va utiliser pour s’authentifier sur le serveur Constellation
  • “AutoStart” (facultatif, par defaut true) : indique si le package doit automatiquement démarrer lorsque sa sentinelle démarre

Supprimer une instance d’un package

Pour supprimer un package sur une sentinelle de votre Constellation :

• Action : “/sentinels/{sentinel}/packages/{packageName}” (DELETE)
• Paramètres : aucun

Options de récupération d’une instance d’un package

Pour récupérer les options de récupération d’une instance d’un package :

• Action : “/sentinels/{sentinelName}/packages/{packageName}/recoveryoptions” (GET)
• Paramètres : aucun

Exemple :

Pour les redéfinir vous devez poster la nouvelle valeur de votre objet “RecoveryOptions” sur cette même URI.

• Action : “/sentinels/{sentinelName}/packages/{packageName}/recoveryoptions” (POST)
• Paramètres : aucun
• Corps de la requête (application/json) : l’objet “RecoveryOptions” avec les nouvelles valeurs

Groupes d’une instance d’un package

Pour récupérer les groupes d’une instance d’un package :

• Action : “/sentinels/{sentinelName}/packages/{packageName}/groups” (GET)
• Paramètres : aucun

Exemple :

Utilisez cette même URI pour poster la nouvelle liste des groupes de votre instance :

• Action : “/sentinels/{sentinelName}/packages/{packageName}/groups” (POST)
• Paramètres : aucun
• Corps de la requête (application/json) : la liste des groupes de votre instance

Settings d’une instance d’un package

Pour récupérer les settings d’une instance d’un package :

• Action : “/sentinels/{sentinelName}/packages/{packageName}/settings” (GET)
• Paramètres : aucun

Exemple :

Utilisez cette même URI pour poster le nouveau dictionnaire (clé/valeur) des settings :

• Action : “/sentinels/{sentinelName}/packages/{packageName}/settings” (POST)
• Paramètres : aucun
• Corps de la requête (application/json) : le dictionnaire (clé/valeur) des settings de votre instance

Gestion des credentials et autorisations

Lister les credentials

Pour récupérer la liste des credentials de votre Constellation :

• Action : “/credentials” (GET)
• Paramètres :
  • includeAccessKeys (optionnel – par défaut “false”) : indique si vous souhaitez inclure les AccessKeys de chaque credentials

Exemple :

Ajouter ou modifier un credential

Pour ajouter ou modifier un credential de votre Constellation :

• Action : “/credentials” (POST)
• Paramètres : aucun
• Corps de la requête (application/json) : un objet JSON contenant six propriétés :
  • “Name” : le nom du credential
  • “AccessKey” : la clé d’accès du credential
  • “Enable” (true par défaut) : indique si le credential est activé ou désactivé
  • “EnableControlHub” (false par défaut) : indique si le credential peut se connecter sur le hub de contrôle (pour l’administration de la Constellation)
  • “EnableManagementAPI” (false par défaut) : indique si le credential peut se connecter à l’API de Management (pour l’édition de la configuration)
  • “EnableDeveloperAccess” (false par défaut) : indique si le credential peut utiliser la sentinelle virtuelle “Developer” pour debugger des packages (utilisé par le SDK Visual Studio)

Supprimer un credential

Pour supprimer un credential de votre Constellation :

• Action : “/credentials/{credentialName}” (DELETE)
• Paramètres : aucun

Récupérer les autorisations d’un credential

• Action : “/credentials/{credentialName}/authorizations” (GET)
• Paramètres : aucun

Vous récupérerez un objet de type “CredentialAuthorizations“ sérialisé en JSON

Définir les autorisations d’un credential

• Action : “/credentials/{credentialName}/authorizations” (POST)
• Paramètres : aucun
• Corps de la requête (application/json) : l’objet CredentialAuthorizations sérialisé en JSON

Editer la page sur GitHub