Product Update: Introducing the Distelli API

By Brian McGehee
Sep 17, 2015

In this blog, I’ll discuss getting started with the new Distelli API. This will include examples using the curl command and several language specific examples.

You can find full documentation for the Distelli API on the Distelli documentation site.

The Distelli API

The Distelli API is a RESTful application program interface (API). The API provides an interface to the Distelli SaaS providing users with the ability to interact with objects in Distelli, including:

  • Deploying applications
  • Listing and inspecting builds
  • Adding servers to environments
  • Setting environment variables
  • and much more…

Getting Started

Every call to the API requires 2 parameters. These are:

Follow the above steps to retrieve your username and API token.

Here is an example API call that will list the applications in account jdoe.


curl "https://api.distelli.com/jdoe/apps?apiToken=abcdefghijklmnopqrstuvwxyz0123456789z"

Using curl

Curl is a command-line tool for transferring data using various protocols. It is available here. Curl is often installed by default on many OS’s.

The various curl options that may be required for use with the Distelli API include:

-d This specifes the API request will include data in the body. When using this you must use the -H also.
-H "Content-Type: application/json" When specifying json data in the body of the API request, this option is required for curl to interpret the data format.
-i Include the HTTP header results. This may be handy to see the response code if there is no data returned.
-X VERB Specify what type of query. The default is GET. Distelli API verbs include:
  • DELETE
  • GET
  • PATCH
  • POST
  • PUT

Typical Syntax


curl OPTIONS "URL" -d JSON_BODY

Making Distelli API Calls with curl

Different types of calls (GET, DELETE, POST, etc…) require differing options. Except GET, these query verbs require the -X option. Here are some GET examples.

Here is an example GetEnv API call. In this call user jdoe is getting information about environment SA_Linux.


curl -i "https://api.distelli.com/jdoe/envs/SA_Linux?apiToken=abcdefghijklmnopqrstuvwxyz0123456789z"

Here is an example ListAppBuilds API call. In this example user jdoe is listing builds for application gobuilddeploy.


curl -i "https://www.distelli.com/jdoe/apps/gobuilddeploy/builds?apiToken=abcdefghijklmnopqrstuvwxyz0123456789z"

Here is an example ListEnvDeployments API call. In this example user jdoe is listing deployments for environment SA_Linux.

Also of note in this example is the use of pagination. The max_results option tells the API to only return 2 results and the order=desc option tells the API to sort the results descending. For more information on pagination see Distelli API pagination.


curl -i "https://api.distelli.com/jdoe/envs/SA_Linux/deployments?apiToken=abcdefghijklmnopqrstuvwxyz0123456789z8&max_results=2&order=desc"

Including Data in the API Call

The Distelli API accepts and sends json formatted data. To send the data with curl you must include the -d option. The data must be JSON formatted.

For more information on the JSON format, see json.org.

In the below example user jdoe is creating a new application called NewApp1 and adding a description=“This is a description”.


curl -i -X PUT -H "Content-Type: application/json" "https://api.distelli.com/jdoe/apps/NewApp1?apiToken=abcdefghijklmnopqrstuvwxyz0123456789z" -d '{"description": "This is a description"}'

Language Specific Distelli API Client Examples

Below you can find several language specific references for client access to the Distelli API. You can clone the above examples below on Distelli’s public GitHub repository.

nodejs

The below snippet of code requires that you:

  1. npm install node-rest-client
  2. export DISTELLI_USERNAME=YOUR_DISTELLI_USERNAME
  3. export DISTELLI_APITOKEN=YOUR_DISTELLI_TOKEN

The below example will list applications and create an application NewApp001.


var Client = require('node-rest-client').Client;

var apiToken = process.env.DISTELLI_APITOKEN;
var username = process.env.DISTELLI_USERNAME;
var apiurl = "https://api.distelli.com";

client = new Client();

// Example Distelli ListApps GET
client.get(apiurl + '/' + username + '/apps?apiToken=' + apiToken, function(data, response){
            // parsed response body as js object
            console.log(data);
            // raw response
            //console.log(response);
        });

// Example Distelli CreateApp PUT with JSON body
var newappname = "NewApp001"
var jsonbody = {
  description: "This is the new application description"
};

client.put(apiurl + '/' + username + '/apps/' + newappname + '?apiToken=' + apiToken, jsonbody, function(data,response) {
    // parsed response body as js object
    console.log(data);
    // raw response
    //console.log(response);
});

python

The below snippet of code requires that you:

  1. export DISTELLI_USERNAME=YOUR_DISTELLI_USERNAME
  2. export DISTELLI_APITOKEN=YOUR_DISTELLI_TOKEN

The below example will list applications and create an application NewApp002.


import requests
import json
import os

apiToken = os.environ['DISTELLI_APITOKEN']
username = os.environ['DISTELLI_USERNAME']
apiurl = "https://api.distelli.com"

# Example Distelli ListApps call
listappsurl=apiurl + '/' + username + '/apps?apiToken=' + apiToken
response = requests.get(listappsurl)

#Careful, the will print your token
#print(response.url)
print(response.text)

# Example Distelli CreateApp call
newappname = "NewApp002"
jsonbody = json.dumps({'description': 'This is the new application description'})
createappurl=apiurl + '/' + username + '/apps/' + newappname + '?apiToken=' + apiToken
response = requests.put(createappurl, data=jsonbody)

#Careful, the will print your token
#print(response.url)
print(response.text)

ruby

The below snippet of code requires that you:

  1. gem install mime-tyes
  2. gem install netrc
  3. gem install http-cookies
  4. gem install json
  5. gem install rest-client
  6. export DISTELLI_USERNAME=YOUR_DISTELLI_USERNAME
  7. export DISTELLI_APITOKEN=YOUR_DISTELLI_TOKEN

The below example will list applications and create an application NewApp003.


require 'rest-client'
require 'json'

apiToken = ENV["DISTELLI_APITOKEN"]
username = ENV["DISTELLI_USERNAME"]
apiurl = "https://api.distelli.com"

# Example Distelli ListApps call
listappsurl=apiurl + "/" + username + '/apps?apiToken=' + apiToken
response = RestClient.get listappsurl, {:accept => :json}
print response.code
print response.headers
print response.body

# Example Distelli CreateApp call
newappname = "NewApp003"
jsonbody = {:description => "This is the new application description"}.to_json
createappurl=apiurl + '/' + username + '/apps/' + newappname + '?apiToken=' + apiToken
response = RestClient.put createappurl, jsonbody, :content_type => :json, :accept => :json
print response.code
print response.headers
print response.body

If you see this, you have not set the environment variables (step 6 & 7 above).


distelli_api_ruby_example.rb:9:in `+': can't convert nil into String (TypeError)

If the application NewApp003 already exists you will receive an error.

Next Steps

Look through the API documentation available on the Distelli Documentation and Have fun!