How to Use HTTPie to Communicate with APIs from Your Terminal – CloudSavvy IT

HTTPie is an HTTP client for your terminal. Designed as a modern alternative to curl, HTTPie simplifies interaction with APIs by providing clear syntax and automatically formatted output.

Available on Windows, Mac and Linux, installing should be a straightforward affair. Most Linux distributions now include HTTPie in their package repositories, so you can quickly apt, dnf or pacman to start. It is also available through Homebrew for Mac users, and delivered as a Python package through Pip on all three platforms (pip install httpie).

After installation, HTTPie will register it http and https commands in your shell. You now have an easy and expressive way to call API endpoints without leaving your terminal!

Basic commands

At its simplest, HTTPie can pass a URL to an immediately GET request:

http example.com

To send data, specify the correct 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 the correct request headers. Give it -f parameter.

When using the JSON syntax, keep in mind 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

Headers and cookies

To set a request header, specify the header name and value as a colon-separated string:

http GET example.com Authorization:foobar

HTTPie sets a number of headers, such as User-Agent, standard. These can be removed by explicitly specifying them with an empty value.

Cookies are set by defining a string with the cookies as colon separated 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 through the special @ syntax:

http -f POST example.com/form-with-file hello="Hello World" myUpload@~/example.pdf

This works identically to an HTML file imported with name="myUpload". You can instead load data from a file and embed it in the request using the =@ syntax, instead of @.

Sessions

HTTPie has built-in support for persistent sessions. This allows you to reuse request components, such as HTTP headers and cookies, between requests to the same host.

You create and use sessions through the --session parameter. Enter the path to a file that will be used to save your new session as the value.

http --session=./my-session.json GET example.com Authorization:foobar

Data supported by sessions, such as the Authorization header in the above request, is now saved to the file. You can now use the Authorization header – it will be automatically included as defined in your session.

Instead of specifying a session file, you can also use a simple name (--session=example). In that case, HTTPie automatically saves the session in an internally managed file. Each session is linked to the host it comes from, so http --session=example example1.com and http --session=example example2.com exist independently of each other.

Manage output

One of the significant improvements of HTTPie over utilities such as curl is the automatic formatting of responses. JSON bodies are handled particularly well, with proper indentation, alphabetical sorting of objects by their keys, and correct conversion of Unicode characters.

You can customize how the output is displayed with a few different options. The --pretty flag can be set to --all (standard), --colors (colors only), --format (format only) or --none (to disable all output processing and see the raw data).

In addition, you can change the color scheme with the --style flag. The available schedules are auto (the standard), default (use the underlying Pygments library styles), fruity and the popular monokai.

You don’t have to worry about the default formatting when redirecting output to a file. HTTPie will recognize that it is being redirected and just pump through the raw data without applying any formatting. This also means that binary responses, which are never normally sent to the terminal, can be piped into files.

Configuration file

HTTPie supports a basic configuration file that can be used to define default settings. These are applied to any requests you make. The file should be saved in ~/.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 add to HTTPie commands you run:

{
    "default_options": [
        "Authorization:foobar",
        "--pretty=none",
        "--style=monokai"
    ]
}

Any option supported by the HTTPie 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 tool filled with functions that brings HTTP APIs to your terminal. It is a modern alternative to Unix staples such as curl that is designed for regular use by developers and testers. While the syntax can be cumbersome at times, it is generally expressive and memorable.

If you would like to learn more about HTTPie, it is worth taking the time to read the official documentation. All development is done publicly on GitHub, with support on Gitter and StackOverflow.