HTTPie for the interactive half of HTTP work

The curl program is on every machine, used in every doc example and in most scripts that talk to a web service. That's not going to change, and this issue is not an argument against it. It is about the situations where you might want more interactivity and an easier syntax — poke an API by hand, read the response, adjust a header, send it again. The alternative in those cases is HTTPie (http).

For example, here is the curl command for the "create a user" request on JSONPlaceholder (the free fake REST API that echoes your POST back):

And here is the equivalent HTTPie version:

With http, you get a simpler syntax, where the request items (the key=value arguments after the URL) build the body of the request. You use = for passing a JSON string, with no need to quote the value, and := for a raw JSON value (booleans, numbers, nested objects).

The http form is the right pick when you build small JSON bodies field by field, and the curl quoting (the escaped quotes around every string) has ever cost you a debugging session.

With http, you don't need to define the following headers, they are already set on any request:

But they can be overridden; you override a default header with the same syntax you would use to set a new one. Here is an example with the Accept header for a request to api.github.com:

As you can see, the syntax is Header:Value, with : (not =, which would make the value a JSON string). Here is another example that adds a custom request header the server ignores but the request carries:

By the way, the syntax with the curl form has more elements: the -H flag and quotes. Let's come back to the example doing a POST on the fake API, the curl command that sets the Content-Type header is:

The http equivalent to that command is:

Next, see how HTTPie allows you to verify the request headers before the request is sent to the server.

There are two things http does around the request itself. The first is that the response is pretty-printed and colorized (when the terminal supports it). So a JSON output is readable as it arrives, and there is no need to pipe it to jq.

The other thing is the dry-run capability; using the --offline flag will print the exact request without sending it. For example, using this command...

... we get this output:

Note that, for the Authorization header set, since the value contains a space, the whole item needs single quotes for http to treat it as valid.

You may already know that curl's -v flag shows the request too, but after it has been sent. http's --offline needs no server at all, which makes it the safe way to check what a command sends before pointing it at production with real credentials.

This is the right trick when you care about what leaves the machine — auth headers, tokens, request shape — as much as what comes back.

Say you are at the terminal with a stream of data, and you want it in the body of a request without opening an editor. For example:

The producer of the stream is a pipe and the consumer is the request. This works from a script too, but there is a case when the technique does not work: when piping and passing request items at the same time. In those situations, you will get this error message:

This is the right trick when the data is already in a pipe (at the prompt or in a script), and the request body is just where it's going.

JSONPlaceholder answers instantly and echoes your POST back. From there, take any real API you already poke by hand and run the same request once with curl, once with http. Count what you had to type.