When you're deploying and managing your awesome Stacks with Cloud 66, you're probably either using our web interface, or our CLI toolbelt called CX.
But did you know there's a third option for deploying, managing and doing even more automated stuff? Let me intro you to our powerful API, which is available to both Cloud 66 for Rails and Cloud 66 for Docker users.
Why use an API?
Well you probably love automation and want to rid yourself of any heavy-lifting so you can focus on your application and not your infrastructure. Using our powerful our API, you can do all the stuff you normally do with the web interface or CX in a programmatical way.
For example, have a look at how one of our customers is using the API to create new Docker containers on the fly. You can do a lot of cool stuff like creating new stacks, redeploying stacks, scale your servers and services up and down, copy files for your server, manage your backups and so much more. Keen to know more?
Let's go!
Prior to doing anything, I'd recommend you take a look at our API documentation. The best way to get started before writing any code is to install the awesome Chrome plugin called Postman. With Postman, we can simply test all the API calls and learn how to use the API to our advantage. Or just use curl.
If you're going to create a client facing integration, you need to implement OAuth2 authentication. For now, I'll assume you're going to use it for automation and run it server side using a personal access token.
To obtain a personal access token you'll need to first generate one.
Go to: https://app.cloud66.com/oauth/authorized_applications
Create a new token https://app.cloud66.com/personal_tokens/new
Give your new token a name
Specify the scope of the token, in the document we describe what kind of scope your need to make the API call.
Copy the access token and store it safely!
WARNING: this is a secret access token; if someone obtains that token, they can take control your stacks.
Your first request
Your access token is a 64-character string, and will look something like this:
ubg5kvaowx6ngpp9pex63pe75bxsjrzia0gcp60y6tmieeg1iwi7fh0fen9nce56.
(BTW - this is a fake one!)
The base URL of our API endpoints = https://app.cloud66.com/api/3/.
You can make a call using curl for example like this:curl -X GET "https://app.cloud66.com/api/3/stacks.json" -H "Authorization: Bearer ubg5kvaowx6ngpp9pex63pe75bxsjrzia0gcp60y6tmieeg1iwi7fh0fen9nce56"
Or use Postman:
If you make a successful request to the /api/3/stacks endpoint, you'll get a list of all your running stacks.
Stack Unique ID
Many requests in the Cloud 66 API rely on the Stack UID value, an alphanumeric string that uniquely identifies your stack. You can retrieve this value by accessing the Stack information page from the right sidebar of your stack page, or by submitting an API request to list all stacks. The Stack UID appears in the response body for each stack you maintain.
You can find the Stack UID here: https://app.cloud66.com/stacks/xxx/information
Change the xxx with the ID of your stack, which is different then the Stack UID.
Get a list of running services
If you have, for example a Docker stack running, you can obtain the list of all running services by doing this:
curl -X GET "https://app.cloud66.com/api/3/stacks/STACK_UID/services" -H "Authorization: Bearer ACCESS_TOKEN"
Restart a service
Of course, not all requests are synchronous. The Cloud 66 API uses both synchronous and asynchronous methods. Asynchronous methods are specified in the documentation for the associated calls; all others are generally considered synchronous.
Asynchronous methods will submit the request to the server, but the application will not wait for a response from the server to continue processing. When the server returns a response, the application can execute a callback function to retrieve the response object, but will continue processing until the response is received.
Example
For these examples, we're using a fake STACK_UID ( ubg5kv ) and a fake ACCESS_TOKEN ( 6ngpp9 ).
If you want to restart all the services, you can call the /api/3/stacks/STACK_UID/action endpoint with the command service_restart.
Because restarting services can take some time, the request will give us back a resource_id, which you can poll the stack action to see if the service_restart is done.
- Step 1: Make the request to restart the services:
curl -X POST "https://app.cloud66.com/api/3/stacks/ubg5kv/action" -H "Authorization: Bearer 6ngpp9" -d command=service_restart
We got a resource_id ( 283 ) as the response.
- Step 2: Check if the request is executed successfully in time:
We're using the following endpoint: /api/3/stacks/STACK_UID/action/ACTION_ID
curl -X GET "https://app.cloud66.com/api/3/stacks/ubg5kv/action/283" -H "Authorization: Bearer 6ngpp9"
We received the status of our action. In the response, we can find the information how it's started (through the API) , when "started_at": "2014-09-01T19:08:05Z", what "action":"service_restart" and if it's successfully executed: "finished_success":true
Have fun!
Using the Cloud 66 API can help you achieve much more automation and do some really interesting stuff with the platform to get more out of your application.
Please reach out to us if you run into any problems using our API, and you can find all the documentation at developers.cloud66.com.