Jelastic Cloud API
Jelastic Cloud API lets developers automate a set of actions required for an application’s lifecycle and extend our platform functionality, by combining other services. Using our API, you can programmatically create environments, deploy apps and perform other tasks that could be earlier accomplished only via Jelastic’s dashboard, but not limited to them.
Jelastic API follows REST principles. REST API determines a set of functions which can be requested by a developer, who then receives a response. The interaction is performed via HTTPS protocol. The advantage of such method is a wide extension of the HTTPS protocol. That’s why REST API can be used with almost any programming language.
Jelastic API Request
All requests of API methods are GET or POST HTTPS-requests to the URL with a set of parameters:
The type of the URL which should be used, is stated in the description of each method (REST field).
The data of the request can be sent as a query string (after the “?” sign) while using the GET method, or in the body of the POST request. Remember, that in case of a GET request, the parameters must be percent encoded (URL encoding).
Since Jelastic 5.1 version, the GET method is no longer supported within the following API requests due to security reasons:
- Signin - https://[hoster-api-host]/1.0/users/authentication/rest/signin?login=[string]&password=[string]
- Signup - https://reg.[hoster-domain]/signup?email=[string]
- Change password - https://[hoster-api-host]/1.0/users/account/rest/changepassword?oldPassword=[string]&newPassword=[string]session=[string]
- GET request for receiving the information which easily fits within the length limitation
- POST request for changing the data (creating environment, changing config files etc.)
In such a way, you won’t be restricted with the request length. Also, such usage is more relevant for the HTTPS protocols specifications.
All of the Jelastic API methods requires authentication and action target details, which are provided through the session and envName parameters respectively.
If there is no envName argument in the method description, it is applied to the whole account/platform. Herewith, the deprecated appid parameter, which was previously used to define action target, should be ignored.
The text value of the parameters should be provided in UTF-8 code. The sequence of the parameters in the request is not important.
Jelastic API Response
The request response is UTF-8 encoded. The response for all API functions is given in JSON format. An example of the result is described in the documentation of the method.
Jelastic API in Action
To start automation of the required processes with Jelastic API you have to face the following requirements:
- You must be registered on any hosting provider with Jelastic support
- You need to download the appropriate Jelastic Client Library (according to the version of used Platform) and add it to classpath
If you are using Maven, add the following dependency to pom.xml
To call any API function you need to be authenticated. The parameter “session” is responsible for authentication, i.e. identifying the user with the request. The session is achieved by calling the Users > Authentication > Signin method.
Where login and password are the credentials of your Jelastic account.
The further calling of the API functions should be performed with the received session value.To complete the working session with API, call the Users > Authentication > Signout method.
With the help of Jelastic Java Client Library you can automate various actions connected with your application lifecycle management, for example: creating an environment, changing its status, deleting, restarting nodes, deploying applications, etc.
Let’s examine how to create an environment with your custom topology and settings using Jelastic Client Library.
A full version of the example on environment creation you can find in Jelastic API documentation (Jelastic Java Samples tab). And here is some step-by-step explanation of the main points:
- Declare a new CreateEnvironment public class which will include all the following blocks and parameters. The first parameters block should contain the next strings:
- <hoster-url> - URL of your hosting provider (Hoster’s URL / API column in this document)
- <email> - your Jelastic account’s email (login)
- <password> - your Jelastic account’s password
- Then the authentication is configured, which will use login and password you’ve specified above.
After authentication, a new unique session is created. It will be used for performing the necessary operations within user’s account. All the further API function calls should be performed within this session, which remains valid until Signout method calling.
- The next step is getting the list of engines available for the specified <engine_type> (can be java, php, ruby, js etc).
- After that get the list of available node templates according to the specified <templates_type>, which can be:
- ALL - all available at platform templates, i.e. native and cartridges
- NATIVE - default node templates
- CARTRIDGE - custom templates, that were added to the platform as cartridges by hosting provider
- The next block is devoted to the custom configurations and settings of your new environment and servers it will contain. More details on JSON parameters, used in Jelastic manifests for defining environment’s topology, can be seen here.
- Finally, initiate the creation of a new environment with all the specified settings:
That’s all. Following such steps you can automate the creation of various environments. Find a full version of this example in Jelastic API docs > Jelastic Java Samples > CreateEnvironment. Also among those Jelastic Java Samples you can find other examples of Jelastic Client Library usage for automation different actions pertaining to your application lifecycle management. Enjoy!