When I want to play around with an API, I usually toss a couple example calls from the command line as an initial test. The go-to application for command line HTTP calls has long been cURL. However, it's usage can be complex and arcane. I often find myself forgetting command line options, retreating to the man page and defeating the purpose of making a quick call.

As handy as cURL is, I was pleased to discover HTTPie, a cURL replacement that is particularly well-suited to JSON-based REST APIs. Below I’ll use a few example calls to CenturyLink Runner to show off some of HTTPie’s features.

Get a Bearer Token

To use any Runner commands, you need to first get a bearer token. Here's how you would do that via the command line in cURL and HTTPie.

Note: In all of these commands, replace "YOUR.USERNAME" with your CenturyLink Cloud username, and "YOUR.PASSWORD" with your password.

First, in cURL:

curl -s -H "Content-Type: application/json" \
   -XPOST https://api.ctl.io/v2/authentication/login \
   --data '{"username":"YOUR.USERNAME","password":"YOUR.PASSWORD"}'

Then, in HTTPie:

http POST https://api.ctl.io/v2/authentication/login \
   'username=YOUR.USERNAME' 'password=YOUR.PASSWORD'

The first thing you’ll notice is that the HTTPie version is shorter. JSON APIs are common, so HTTPie assumes that’s what’s coming. In fact, HTTPie makes a lot of assumptions that make it a good tool for a specific job, whereas cURL is much more general. In addition to automatically setting the Content-type, HTTPie automatically converts key=value items into JSON, which means the end of escaping quotes. You just need to make sure you use = for string values and := for non-strings.

Note: Record the accountAlias and bearerToken results from one of your shell commands. We will be using it in the next section.

Get Datacenter Information

Note: In the URLs below, replace XXX with the three-letter account alias for your account. Replace the "BEARER.TOKEN" with the bearer token you recorded in the last section. Also, these commands are addressing the "WA1" datacenter. If you want to use a different datacenter, use its code in the URL.

cURL:

curl -XGET -H 'Authorization: Bearer BEARER.TOKEN' \
    https://api.ctl.io/v2/datacenters/XXX/WA1

HTTPie:

http GET https://api.ctl.io/v2/datacenters/XXX/WA1 \
    'Authorization:Bearer BEARER.TOKEN'

Retrieving datacenter information looks essentially the same. HTTPie doesn’t require a flag before the request method. In this example, neither need a request method at all because cURL and HTTPie both assume GET.

The biggest difference you’ll notice is in the response, which is automatically color-coded and JSON is formatted. These defaults make HTTPie very friendly to my tired developer eyes.

httpie-300x300.png

Create a Server Group

cURL:

curl -s -XPOST -H 'Authorization: Bearer BEARER.TOKEN' \
    -H 'Content-Type: application/json' \
    --data '{"name":"CurlGroup1","parentgroupid":"f0f49dc6d0024bf68a0807e2b0fe32ea","description":"Example of new group","locationId":"WA1"}' \
    https://api.ctl.io/v2/groups/XXX

HTTPie

http POST https://api.ctl.io/v2/groups/XXX \
    name=PieGroup1 parentgroupid='f0f49dc6d0024bf68a0807e2b0fe32ea' 'description=Example of new group' locationId=WA1  \
    'Authorization:Bearer BEARER.TOKEN'

This command creates a new virtual server group. You will need to look up parentgroupid by navigating to a server group in the CenturyLink Cloud Control Portal. For example, if the group control portal page URL is "https://control.ctl.io/manage#/wa1/group/f0f49dc6d0024bf68a0807e2b0fe32ea", the group ID is "f0f49dc6d0024bf68a0807e2b0fe32ea".

Eliminate That Annoying Bearer Token

Making API calls from the command line often requires a bunch of copy and pasting, most notably of the bearer token. Since the CenturyLink Cloud API uses basic headers to pass authorization, we can eliminate the need for the key after the first call with the session flag:

--session=foo

If you include a session ID along with your API key authentication, then subsequent calls can just include the same session ID. HTTPie also has a feature that allows you to set your own defaults. Just edit your config.json to always pass the session ID (or any other flags you want set with every call):

  "default_options": ["--session=foo"]

You can edit the default options in ~/.httpie/config.json (or under your Application Data folder in Windows).

Install HTTPie and play with the CenturyLink Cloud API

Try out HTTPie on your favorite new API. HTTPie is written in Python, so if you have the pip package manager, it’s as easy as:

pip install httpie

If you haven’t already, create a CenturyLink Cloud account and try some calls with HTTPie.