Aperçu de l'API plateforme

L’API de la plateforme expose chaque action disponible dans le tableau de bord sous forme d’interface programmatique. Tout flux pilotable via le tableau de bord — cycle de vie d’environnement, déploiement, mise à l’échelle, règles de pare-feu, configuration de nœuds — peut être scripté ou intégré via la même surface HTTP.

Ce que couvre cette page

• L’URL de base et le format de requête — GET vs. POST, encodage des paramètres, limite de longueur d’URL.
• Le fonctionnement de l’authentification via les jetons de session.
• Comment les espaces de noms API correspondent aux actions de la plateforme, y compris l’espace de noms pare-feu environment > Security.
• La bibliothèque cliente Java pour des appels typés et encapsulés.
• Un exemple concret de création d’environnement avec le client Java.
• La relation entre le CLI et l’API, et quand Cloud Scripting (JPS) est le meilleur outil.

Format de requête

Tous les appels API sont des requêtes HTTPS GET ou POST vers :

https://{api-host}/1.0/

L’URL complète pour chaque méthode est documentée dans le champ REST de cette méthode. Les paramètres peuvent être fournis comme chaîne de requête (pour GET) ou dans le corps de la requête (pour POST). Pour les requêtes GET, les valeurs de paramètres doivent être encodées au format pourcent.

La limite de longueur d’URL est de 2 048 caractères. Deux implications pratiques :

• Utilisez GET pour les opérations de lecture dont les paramètres tiennent confortablement dans la limite.
• Utilisez POST pour les opérations d’écriture et toute requête avec des paramètres volumineux ou complexes (créer un environnement, téléverser un fichier de configuration, etc.).

Pour des raisons de sécurité, GET n’est pas pris en charge pour les opérations suivantes :

• Signin — https://{api-host}/1.0/users/authentication/rest/signin?login=[string]&password=[string]
• Signup — https://reg.{platform-domain}/signup?email=[string]
• Change password — https://{api-host}/1.0/users/account/rest/changepassword?oldPassword=[string]&newPassword=[string]&session=[string]

Les valeurs textuelles de paramètres doivent être encodées en UTF-8. L’ordre des paramètres dans la requête n’a pas d’importance.

Toutes les méthodes requièrent l’authentification via le paramètre session. La plupart des méthodes ont aussi besoin d’un identifiant cible — typiquement envName pour les opérations limitées à un environnement. Les méthodes sans envName s’appliquent à tout le compte. Le paramètre déprécié appid doit être ignoré.

Format de réponse

Les réponses sont en JSON encodé UTF-8. La structure est documentée par méthode.

Authentification

La session est établie en appelant Users > Authentication > Signin :

https://{api-host}/1.0/users/authentication/rest/signin?login=[string]&password=[string]

login et password sont les identifiants de votre compte plateforme. La réponse inclut un jeton session. Chaque appel API suivant fournit ce jeton comme paramètre session.

Terminez la session avec Users > Authentication > Signout :

https://{api-host}/1.0/users/authentication/rest/signout?session=[string]

Espaces de noms API

Les actions de la plateforme sont regroupées en espaces de noms. Le chemin de l’espace de noms forme le segment d’URL entre /1.0/ et /rest/. Quelques espaces de noms représentatifs :

environment > Security — méthodes de pare-feu

L’espace de noms environment > Security contrôle les règles de pare-feu par conteneur de façon programmatique. Les méthodes documentées sont :

Ces méthodes sont aussi les opérations sous-jacentes de l’interface pare-feu dans le tableau de bord — l’API et le tableau de bord agissent sur le même jeu de règles. Voir la page règles de pare-feu du conteneur pour la procédure via l’interface et le modèle de priorité des règles.

Bibliothèque cliente Java

Pour les applications Java, la plateforme livre une bibliothèque cliente empaquetée Maven. Ajoutez la dépendance à pom.xml :

<dependency>
   <groupId>com.jelastic</groupId>
   <artifactId>jelastic-public-j2se</artifactId>
   <version>3.1</version>
</dependency>

La bibliothèque encapsule les appels HTTPS, gère l’authentification et les nouvelles tentatives, et fournit des réponses typées pour chaque méthode API.

Exemple : créer un environnement

Une procédure pas à pas utilisant le client Java pour créer un environnement PHP. Le même modèle s’applique à toute autre opération API.

1. Déclarer la configuration

private final static String HOSTER_URL = "<hoster-url>";
private final static String USER_EMAIL = "<email>";
private final static String USER_PASSWORD = "<password>";
private final static String ENV_NAME = "test-api-environment-" + new Random().nextInt(100);

• <hoster-url> — l’hôte API de la plateforme.
• <email> — votre courriel de compte plateforme.
• <password> — votre mot de passe de compte plateforme.

2. S’authentifier

public static void main(String[] args) {
    System.out.println("Authenticate user...");
    AuthenticationResponse authenticationResponse = authenticationService.signin(USER_EMAIL, USER_PASSWORD);
    System.out.println("Signin response: " + authenticationResponse);
    if (!authenticationResponse.isOK()) {
        System.exit(authenticationResponse.getResult());
    }
    final String session = authenticationResponse.getSession();

La session retournée est utilisée pour chaque appel suivant jusqu’à la déconnexion.

3. Obtenir les moteurs et gabarits disponibles

System.out.println("Getting list of engines...");
ArrayResponse arrayResponse = environmentService.getEngineList(session, "<engine_type>");
// engine_type peut être java, php, ruby, js, etc.

System.out.println("Getting list of templates...");
arrayResponse = environmentService.getTemplates(session, "<templates_type>", false);
// templates_type : ALL, NATIVE ou CARTRIDGE

ALL retourne tous les gabarits disponibles. NATIVE retourne les gabarits de nœud fournis par la plateforme. CARTRIDGE retourne les gabarits personnalisés ajoutés par l’opérateur de la plateforme.

4. Définir la topologie

JSONObject env = new JSONObject()
        .put("ishaenabled", false)
        .put("engine", "php5.5")
        .put("shortdomain", ENV_NAME);

JSONObject apacheNode = new JSONObject()
        .put("nodeType", "apache2")
        .put("extip", false)
        .put("count", 1)
        .put("fixedCloudlets", 1)
        .put("flexibleCloudlets", 4);

JSONObject mysqlNode = new JSONObject()
        .put("nodeType", "mysql5")
        .put("extip", false)
        .put("fixedCloudlets", 1)
        .put("flexibleCloudlets", 4);

JSONObject memcachedNode = new JSONObject()
        .put("nodeType", "memcached");

JSONArray nodes = new JSONArray()
        .put(apacheNode)
        .put(mysqlNode)
        .put(memcachedNode);

La topologie est exprimée en JSON. Les mêmes paramètres sont documentés dans la référence de manifeste de la plateforme.

5. Créer l’environnement

System.out.println("Creating environment...");
ScriptEvalResponse scriptEvalResponse = environmentService.createEnvironment(
    session, "createenv", env.toString(), nodes.toString());
System.out.println("CreateEnvironment response: " + scriptEvalResponse);

La réponse contient l’identifiant de l’environnement créé et son état courant.

Contraintes

• La limite de longueur d’URL de 2 048 caractères s’applique à chaque requête GET. Les jeux de paramètres volumineux doivent passer par POST.
• Les sessions sont établies à chaque appel à Signin ; les scripts de longue durée doivent gérer la durée de vie de la session explicitement et appeler Signout à la fin.
• Le paramètre déprécié appid est accepté par certaines méthodes mais ne doit pas être utilisé dans du nouveau code.

Autres voies d’automatisation

Le CLI (~/jelastic/) encapsule la même API et est un point d’entrée plus simple pour les scripts shell et les opérations ponctuelles. Pour les flux d’automatisation plus larges — provisionner un environnement, déployer du code, configurer des extensions — les manifestes Cloud Scripting (paquets JPS) conviennent généralement mieux que des appels API directs. Les deux chemins atteignent les mêmes actions de plateforme sous-jacentes.

Voir aussi

• CLI de la plateforme
• CLI — installation de paquet JPS
• CLI scaling — changetopology
• Règles de pare-feu du conteneur
• Aperçu du déploiement applicatif