Whether you're building your own API, or using a third-party service, it’s a pretty good idea to make sure you can talk to that API reliably.

HTTPie is a light but powerful open source HTTP client that allows you to easily communicate with APIs straight from the command line.

Developers use HTTPie for testing, debugging and exploring various API endpoints to see how they behave under given conditions. HTTPie comes with colorized output, simple syntax and a number of features to make the exploration a breeze!

This guide covers the basic usage of HTTPie and provides some examples to get you started. ✨

Step 1: Install HTTPie

The best way to ensure you're installing the latest version of HTTPie is to use pip, the Python package installer.

# Make sure we have an up-to-date version of pip and setuptools:
$ python -m pip install --upgrade pip setuptools
$ python -m pip install --upgrade httpie

On macOS, you can also use Homebrew, by running brew install httpie.

HTTPie can also be installed using the source code directly, which is available on GitHub.

HTTPie comes with two commands: http and https. Once it’s been installed, verify that you’ve installed it by running

$ http --version
$ https --version

and make sure they both return the same version. If you're having trouble installing HTTPie, you can always reach out to the HTTPie Discord community!

Step 2: Make your first request 🥇

Completed the installation? Well done! You’re now one step closer to being able to poke and explore various APIs.

Make a Hello World request:

# The server should say hello back to you!
$ https httpie.io/hello

If you don't specify any request parameters (e.g. some JSON; we'll get to it in a second!), then HTTPie uses the HTTP GET method implicitly.

Therefore, the above example is equivalent to:

$ https GET httpie.io/hello

Step 3: Send various HTTP requests with HTTPie

In short, HTTPie commands use the following format:

$ http [flags] [METHOD] URL [ITEM [ITEM]]

where flags are HTTPie behaviour parameters, METHOD is HTTP method, URL is the webpage or API URL, and ITEMs are querystring parameters, request data and/or headers.

Run http --help or see the docs to see all available flag options.

HTTP vs HTTPS

HTTPie comes with http and https commands preinstalled to account for both HTTP and HTTPS requests that you're going to make.

In the above example, we use https to make a request to httpie.io/hello as a shorthand to indicate that https://httpie.io/hello should be queried.

The following is also perfectly valid:

$ http https://httpie.io/hello

HTTP Methods

[METHOD] is an optional HTTPie parameter. If you don't specify any request data in your command, then we already know that GET is going to be used by default. You don't need to type it out.

# Get the top GitHub search result for search term "httpie"
$ https api.github.com/search/repositories?q=httpie&per_page=1

But wait! The above can be simplified. 😏

If you want to add querystring parameters (note: querystring parameters are the ones that appear in the URL as ?param1=value1&param2=value2, not JSON data), use the == shorthand:

# Get the top GitHub search result for search term "httpie"
$ https api.github.com/search/repositories q==httpie per_page==1

If you do specify some request data, then HTTPie will use the HTTP POST method by default.

You can manually set any HTTP method you need by specifying it in the command: GET, POST, PUT, DELETE, PATCH and others.

Data

To make a request with some querystring parameters, use the syntax described in the above section.

You can specify request parameters in JSON using HTTPie's shorthand syntax in your http or https command.

= is for string values, := for raw JSON, :=@ for JSON files and =@ for regular files.

$ http PUT pie.dev/put \
    name=John \                        # String (default)
    age:=29 \                          # Raw JSON — Number
    married:=false \                   # Raw JSON — Boolean
    hobbies:='["http", "pies"]' \      # Raw JSON — Array
    favorite:='{"tool": "HTTPie"}' \   # Raw JSON — Object
    bookmarks:=@files/data.json \      # Embed JSON file
    description=@files/text.txt        # Embed text file

HTTPie also lets you submit data as form data. See the docs on forms to learn how.

Headers

By default, HTTPie appends the following headers to your request:

GET / HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
User-Agent: HTTPie/<version>
Host: <taken-from-URL>

You can override these headers, or set your own. Just use the Header:Value notation, like this:

$ http pie.dev/headers 'Custom-Header-Name:Custom Header Value'

For details on how to send cookies and authorization headers, or how to work with response headers, see the docs.

If you've got any questions about HTTPie, catch me on the HTTPie Discord or Twitter.

That's it for today, folks. Happy hacking!