Walk to DO world of API
API (Application Programming Interface) is a set of protocol or method to communicate with other software or endpoints by sending requests.
DO API allows you to create/manage droplets and other resources using conventional HTTP requests. Basically, whatever you can do with DO Control Panel can be performed via API apart from the generation of OAuth Tokens.
OAuth stands for the open standard for authorization, a substitute to user/password authentication. This is a mechanism used by Google, Facebook, Twitter, etc to permit the users to share information about their accounts with third party applications or websites.
To make use of DO API, we first need to generate OAuth Tokens to allow API calls to authenticate to your account. This can be done via DO Control panel -> API -> Token section. Once Token is generated, you can use API to retrieve or execute actions using various request methods like GET, POST etc. Requests can be made with any tool like curl fluent in HTTP. DO features 5K requests/hour per OAuth token which is referred as Rate Limit.
CURL: It is a tool use to transfer data from or to a server, using one of the supported protocols (HTTP, HTTPS, FTP, IMAP, POP3, SCP, SMB, TELNET etc).
Syntax:
curl [options] [URL...]
General Options:
-H : Specify a custom HTTP header to pass to the server
-i : include protocol headers in the output
-I : include only header in the output (no body response)
-X : Specify a request command in use
-d : (HTTP) Sends the specified data in a POST request to the HTTP server
URL: Target Endpoint (https://api.digitalocean.com/v2/account)
Authenticate API Request with your DO account:
This can be done by sending a bearer authorization header with your request. It is a preferred way as it completes authentication in the header using '-H' flag.
curl -H "Authorization: Bearer $TOKEN" -X $HTTP_METHOD "Endpoint URL"
Note: Assign or replace $TOKEN variable with the actual value of Token.
$HTTP_METHOD indicates actions to be performed on the desired resource. Actions can be performed using following methods:
In response, it returns 'header' and 'body' objects. For example:
1. API call to get DO Account information:
Recommended by LinkedIn
curl -H "Authorization: Bearer $TOKEN" -iX GET -H "Content-Type: application/json" "https://api.digitalocean.com/v2/account"
Output is shown below:
Within Header, it includes RateLimit and general header information, whereas, in the Body section, actually GET request information is shown. As Target URL/Endpoint has '/v2/account/', body section details general DO account information and sometimes also shows 'links' (last, next), if pagination is enabled and output data is high in number.
Similar you can retrieve or perform actions on various endpoints. A few popular endpoints are given below:
https://api.digitalocean.com/v2/account
https://api.digitalocean.com/v2/droplets
https://api.digitalocean.com/v2/volumes
https://api.digitalocean.com/v2/domains
https://api.digitalocean.com/v2/tags
Apart from retrieving information from your account, you can create/manipulate your account information using POST, PUT, DELETE methods. Let's create a new droplet using POST request:
curl -H "Authorization: Bearer $TOKEN" -X POST -iH "Content-Type: application/json" -d '{"name":"example.com","region":"nyc3","size":"512mb","image":"ubuntu-14-04-x64","ssh_keys":null,"backups":false,"ipv6":true,"user_data":null,"private_networking":true,"volumes": null,"tags":["project"]}' "https://api.digitalocean.com/v2/droplets"
In the above command, we used the curl '-d' flag to send data to the POST request, which will be used by the Endpoint to configure a new droplet. For detailed information on all the available DO Endpoints, please refer to DO Documentation.
I hope the above will help you to understand the world of API and how DO API works. Rest, feel free to comment, tweet or email on chirag01jain@gmail.com to share feedback :)