HTTPie is an HTTP client for your terminal. Designed as a modern alternative to curl, HTTPie simplifies interaction with APIs by offering a straightforward syntax and automatically formatted output.
Available on Windows, Mac and Linux, getting setup should be a straightforward affair. Most Linux distributions now include HTTPie within their package repositories, so you can quickly apt, dnf or pacman to begin. It’s also available via Homebrew for Mac users, and as a Python package delivered via Pip on all three platforms (pip install httpie).
Once installed, HTTPie registers the http and https commands in your shell. You’ve now got a simple and expressive way to call API endpoints without leaving your terminal!
Basic Commands
At its simplest, HTTPie can be passed a URL to immediately make a GET request:
http example.com
To send data, specify the appropriate HTTP verb and then pass your key/value pairs as additional command-line parameters:
http POST example.com foo=bar hello=world
By default, data is sent as JSON with appropriate request headers. To submit as a form instead, pass the -f parameter.
When using the JSON syntax, be aware that all fields are normally sent as strings. You can use the := syntax instead of = to switch to raw data mode. A parameter examples:='[1, 2]' will then result in the examples key being set to an array of two integers.
Headers and Cookies
To set a request header, specify the header’s name and value as a colon-separated string:
http GET example.com Authorization:foobar
HTTPie sets some headers, such as User-Agent, by default. These can be removed by explicitly specifying them with an empty value.
Cookies are set by defining a string with the cookies as colon-delimited values:
http GET example.com "Cookie:foo=bar;hello=world"
This is really just a special case of setting the Cookie header, which is how cookies are sent over HTTP.
Working With Files
You can upload and download files using standard shell redirects:
http POST example.com/upload < ~/example.pdf http GET example.com/download.pdf > ~/download.pdf
You can also upload files as part of an HTTP form submission by using the special @ syntax:
http -f POST example.com/form-with-file hello="Hello World" myUpload@~/example.pdf
This will act identically to an HTML file input with name="myUpload". You may instead load data from a file and embed it into the request using the =@ syntax, instead of @.
Sessions
HTTPie has built-in support for persistent sessions. These allow you to reuse request components, such as HTTP headers and cookies, between requests made to the same host.
You create and use sessions by setting the --session parameter. As its value, specify the path to a file which will be used to store your new session.
http --session=./my-session.json GET example.com Authorization:foobar
Data which is supported by sessions, such as the Authorization header in the above request, will now be saved into the file. On subsequent requests, you may now omit the Authorization header – it’ll be included automatically as it’s defined in your session.
Instead of specifying a session file, you may also use a simple name (--session=example). In this case, HTTPie will automatically save the session to an internally managed file. Each session is tied to the host it originates from, so http --session=example example1.com and http --session=example example2.com will exist independently of each other.
Managing Output
One of HTTPie’s significant improvements over utilities like curl is its automatic formatting of responses. JSON bodies are particularly well-handled, with proper indentation, alphabetical sorting of objects by their keys and correct conversion of Unicode characters.
You can customise how output is rendered using a few different options. The --pretty flag can be set to --all (default), --colors (only colours), --format (only formatting) or --none (to disable all output processing and see the raw data).
In addition, you can change the colour scheme using the --style flag. The available schemes are auto (the default), default (use the underlying Pygments library styles), fruity and the popular monokai.
You don’t need to worry about the default formatting when redirecting output into a file. HTTPie will recognise that it’s being redirected and simply pipe the raw data without applying any formatting. This also means that binary responses, which are never normally emitted to the terminal, can be piped into files.
Configuration File
HTTPie supports a basic configuration file which can be used to define default settings. These will be applied to all requests you make. The file should be saved to ~/.config/httpie/config.json on Linux/Mac and %APPDATA%httpieconfig.json on Windows.
A single configuration key is supported, default_options, which accepts a basic array of parameters to append to HTTPie commands you execute:
{
"default_options": [
"Authorization:foobar",
"--pretty=none",
"--style=monokai"
]
}
Any option which is supported by HTTPie’s command-line interface can be included. You can override your default options by defining them with a new value each time you run HTTPie.
Conclusion
HTTPie is a feature-filled tool that brings HTTP APIs to your terminal. Its a modern alternative to Unix staples like curl that’s designed for regular use by developers and testers. Although the syntax can be cumbersome at times, it’s generally expressive and memorable.
It’s worth taking the time to read the official documentation if you’re looking to learn more about HTTPie. All development occurs in the open on GitHub, with support provided on Gitter and StackOverflow.
