cURL vs HTTPie on the Command Line for HTTP APIs

(Originally appeared on the Orchestrate Blog)

June 20, 2014

Share +

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.

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.

Search a collection

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: