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. Our own API reference defaults to sample calls with cURL, which works fine for copy-paste. But I find myself forgetting command line tags, 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 Orchestrate to show off some of HTTPie’s features.

Add an item to a collection

curl -u "YOUR_API_KEY_HERE:" -XPUT -d "{\"name\": \"Bicep Curls\", \"reps\": 10, \"weight\": 25}" -H "Content-type: application/json" https://api.orchestrate.io/v0/workouts/bicep
http -a "YOUR_API_KEY_HERE:" PUT https://api.orchestrate.io/v0/workouts/bicep name="Bicep Curls" weight:=25 reps:=10

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.

Get an item from a collection

curl -XGET -u "YOUR_API_KEY_HERE:" https://api.orchestrate.io/v0/workouts/bicep
http -a "YOUR_API_KEY_HERE:" https://api.orchestrate.io/v0/workouts/bicephttpie

Retrieving an item 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

Search a collection

curl -u "YOUR_API_KEY_HERE:" "https://api.orchestrate.io/v0/workouts/?query=reps:%5B0%20TO%2011%5D"
http -a "YOUR_API_KEY_HERE:" https://api.orchestrate.io/v0/workouts/ query=="reps:[0 TO 11]"

To perform a search using Orchestrate, we need a query string. To use a query string with cURL, we can build the true URL, with all characters encoded, adding the question mark to note the query. However, due to the less-than symbol in my query, the entire URL needs to be quoted in the cURL version. HTTPie allows me to add query string parameters using == and tossing values into the command similar to passing JSON data. For RESTful APIs, this means it’s easy to transition from a PUT command to a query without needing to edit the URL directly.

Eliminate that annoying API Key

Making API calls from the command line often requires a bunch of copy and pasting, most notably of the API key. Since Orchestrate uses basic authentication over SSL, 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 features that allow 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 Orchestrate

Try out HTTPie on your favorite new API, which I really think should be Orchestrate. 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 free Orchestrate account and try some calls with HTTPie.

Photo by Lizard10979