Getting started with HTTPie
Tags: tooling, tutorial, webdev
Published: 2021-06-10 15:57:38

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.

![HTTPie in the terminal](https://raw.githubusercontent.com/httpie/httpie/master/httpie.gif)

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](https://pypi.org/project/pip/).

```bash
# 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](http://github.com/httpie/httpie).

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

```bash
$ 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](https://httpie.io/chat) 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:

```bash
# 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](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/GET) implicitly.

Therefore, the above example is equivalent to:

```bash
$ https GET httpie.io/hello
```

## Step 3: Send various HTTP requests with HTTPie

In short, HTTPie commands use the following format:

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

where `flags` are HTTPie behaviour parameters, `METHOD` is HTTP method, `URL` is the webpage or API URL, and `ITEM`s are [querystring parameters, request data and/or headers](https://httpie.io/docs#request-items). 

Run `http --help` or see the [docs](http://httpie.io/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:

```bash
$ 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.

```bash
# 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:

```bash
# 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](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST) 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](https://httpie.io/docs#forms) to learn how.

### Headers

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

```bash
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:

```bash
$ 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](https://httpie.io/docs#cookies).

---

If you've got any questions about HTTPie, catch me on the [HTTPie Discord](https://httpie.io/chat) or [Twitter](https://twitter.com/elena_lape).

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