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¶m2=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!
Top comments (4)
Nice article.
Though can't we do all this by using Postman or (my favorite) Insomnia?
Is there anything extra that HTTPie offers that I missed in your article?
I think its power is appreciated when you are in a headless environment like SSHing into a server or container. Also could work for validation on CICD workflows. There are folks that like terminal more than anything else….including myself LOL
Exactly. Also, I think if you're already using the terminal for something else, then using HTTPie means using one less additional tool, and less window switching.
Insomnia was probably the first API poking tool I've ever used! The HTTPie CLI is very similar, except it provides a different type of interface (the terminal), and you can also use it in scripts.