HTTPie for API testing

CLI

Installation

Universal

1

python -m pip install install httpie

ArcoLinux

1

$ pacman -S httpie

Usage

Synopsis:

1

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

1

$ http --help

Examples

General

Synopsis:

1

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

Custom HTTP method, HTTP headers and JSON data:

1

$ http PUT pie.dev/put X-API-Token:123 name=John

Each request item is simply a key/value pair separated with the following characters: : (headers), = (data field, e.g., JSON, form), := (raw data field) == (query parameters), @ (file upload).

1
2
3
4
5


http PUT pie.dev/put \
    X-Date:today \                     # Header
    token==secret \                    # Query parameter
    name=John \                        # Data field
    age:=29                            # Raw JSON

Verbose

By default, HTTPie only outputs the final response. Print the whole HTTP exchange (request and response) using -v:

1

$ http -v pie.dev/get

1

$ http -vv pie.dev/get

Offline

Build and print a request without sending it using offline mode:

1

$ http --offline pie.dev/post hello=offline

See the request that is being sent using one of the output options:

1

$ http -v pie.dev/get

HTTP method

There are no restrictions regarding which request methods can include a body. You can send an empty POST request:

1

$ http POST pie.dev/post

You can also make GET requests containing a body:

1

$ http GET pie.dev/get hello=world

Optional GET and POST The METHOD argument is optional, and when you don’t specify it, HTTPie defaults to:

GET for requests without body
POST for requests with body

Headers

To set custom headers you can use the Header:Value notation.

Set a custom Host header to work around missing DNS records:

1
2
3
4


$ http localhost:8000 Host:example.com
$ http localhost:8000 User-Agent:HTTPie/<version>
$ http localhost:8000 Accept-Encoding:gzip, deflate
$ http localhost:8000 Accept:*/*

To unset a previously specified header (such a one of the default headers), use Header::

1

http pie.dev/headers Accept: User-Agent:

Cookies

HTTP clients send cookies to the server as regular HTTP headers.

1

$ http pie.dev/cookies 'Cookie:sessionid=foo;another-cookie=bar'

Request URL

The default scheme is http:// and can be omitted from the argument.

HTTPie also installs an https executable, where the default scheme is https://

URL for localhost can be omitted, If the port is omitted, then port 80 is assumed.

1

$ http :/foo

1
2


GET /foo HTTP/1.1
Host: localhost

1

$ http :3000/bar

1
2


GET /bar HTTP/1.1
Host: localhost:3000

1

$ http :

1
2


GET / HTTP/1.1
Host: localhost

Querystring parameters

The param==value syntax for appending URL parameters. Any special characters in the parameter name or value get automatically URL-escaped.

JSON

JSON is also the implicit content type HTTPie uses by default.

1

$ http PUT pie.dev/put name=John email=john@example.org

1
2
3
4
5
6
7
8
9


PUT / HTTP/1.1
Accept: application/json, */*;q=0.5
Accept-Encoding: gzip, deflate
Content-Type: application/json
Host: pie.dev
{
    "name": "John",
    "email": "john@example.org"
}

You can use --json, -j to explicitly set Accept to application/json regardless of whether you are sending data

1

$ http --json PUT pie.dev/put name=John email=john@example.org

Non-string JSON fields

Non-string JSON fields use the := separator, which allows you to embed arbitrary JSON data into the resulting JSON object. Additionally, text and raw JSON files can also be embedded into fields using =@ and :=@:

1
2
3
4
5
6
7
8


$ 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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


PUT /person/1 HTTP/1.1
Accept: application/json, */*;q=0.5
Content-Type: application/json
Host: pie.dev
{
    "age": 29,
    "hobbies": 
        "http",
        "pies"
    ],
    "description": "John is a nice guy who likes pies.",
    "married": false,
    "name": "John",
    "favorite": {
        "tool": "HTTPie"
    },
    "bookmarks": {
        "HTTPie": "https://httpie.org",
    }
}

Nested JSON

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


http pie.dev/post \
  platformname]=HTTPie \
  platformabout]mission]='Make APIs simple and intuitive' \
  platformabout]homepage]=httpie.io \
  platformabout]homepage]=httpie.io \
  platformabout]stars]:=54000 \
  platformapps]]=Terminal \
  platformapps]]=Desktop \
  platformapps]]=Web \
  platformapps]]=Mobile

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


{
    "platform": {
        "name": "HTTPie",
        "about": {
            "mission": "Make APIs simple and intuitive",
            "homepage": "httpie.io",
            "stars": 54000
        },
        "apps": 
            "Terminal",
            "Desktop",
            "Web",
            "Mobile"
        ]
    }
}

query

1
2
3
4


$ http --offline --print=B pie.dev/post \
  category=tools \
  search[type]=id \
  search[id]:=1

1
2
3
4
5
6
7


{
    "category": "tools",
    "search": {
        "id": 1,
        "type": "id"
    }
}

create an array in the given path (if there is not one already), and append the given value to that array.

1
2
3
4
5


$ http --offline --print=B pie.dev/post \
  category=tools \
  search[type]=keyword \
  search[keywords][]=APIs \
  search[keywords][]=CLI

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


{
    "category": "tools",
    "search": {
        "keywords": [
            "APIs",
            "CLI"
        ],
        "type": "keyword"
    }
}

explicitly specify the position of elements inside an array, If there are any missing indexes, HTTPie will nullify them in order to create a concrete object that can be sent:

1
2
3
4
5
6


http --offline --print=B pie.dev/post \
  category=tools \
  search[type]=platforms \
  search[platforms][]=Terminal \
  search[platforms][1]=Desktop \
  search[platforms][3]=Mobile

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


{
    "category": "tools",
    "search": {
        "platforms": [
            "Terminal",
            "Desktop",
            null,
            "Mobile"
        ],
        "type": "platforms"
    }
}

embed raw JSON to a nested structure

1
2
3
4
5
6


$ http --offline --print=B pie.dev/post \
  category=tools \
  search[type]=platforms \
  'search[platforms]:=["Terminal", "Desktop"]' \
  search[platforms][]=Web \
  search[platforms][]=Mobile

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


{
    "category": "tools",
    "search": {
        "platforms": [
            "Terminal",
            "Desktop",
            "Web",
            "Mobile"
        ],
        "type": "platforms"
    }
}

Raw JSON

1

$ echo -n '{"hello": "world"}' | http POST pie.dev/post

1

$ http POST pie.dev/post < files/data.json

Redirected input

Upload a file using redirected input:

1

$ http pie.dev/post < files/data.json

Download a file and save it via redirected output:

1

$ http pie.dev/image/png > image.png

Download a file wget style:

1

$ http --download pie.dev/image/png

Proxies

You can specify proxies to be used through the --proxy argument for each protocol (which is included in the value in case of redirects across protocols):

1

$ http --proxy=http:http://10.10.1.10:3128 --proxy=https:https://10.10.1.10:1080 example.org

With Basic authentication:

1

$ http --proxy=http:http://user:pass@10.10.1.10:3128 example.org

Environment variables You can also configure proxies by environment variables ALL_PROXY, HTTP_PROXY and HTTPS_PROXY, and the underlying Requests library will pick them up. If you want to disable proxies configured through the environment variables for certain hosts, you can specify them in NO_PROXY. In your ~/.bash_profile:

1
2
3


export HTTP_PROXY=http://10.10.1.10:3128
export HTTPS_PROXY=https://10.10.1.10:1080
export NO_PROXY=localhost,example.com

SOCKS Usage for SOCKS is the same as for other types of proxies:

1

$ http --proxy=http:socks5://user:pass@host:port --proxy=https:socks5://user:pass@host:port example.org

Authentication

Basic auth

1

$ http -a username:password pie.dev/basic-auth/username/password

Password prompt

1

$ http -a username pie.dev/basic-auth/username/password

Empty password

To send an empty password without being prompted for it, include a trailing colon in the credentials:

1

$ http -a username: pie.dev/headers

Digest auth

1

$ http -A digest -a username:password pie.dev/digest-auth/httpie/username/password

Bearer auth

1

$ https -A bearer -a token pie.dev/bearer

Auth plugins

httpie-jwt-auth
ttpie-hmac-auth
httpie-api-auth

HTTP redirects

By default, HTTP redirects are not followed and only the first response is shown.

To instruct HTTPie to follow the Location header of 30x responses and show the final response instead, use the --follow, -F option:

1

$ http --follow pie.dev/redirect/3

With 307 Temporary Redirect and 308 Permanent Redirect, the method and the body of the original request are reused to perform the redirected request. Otherwise, a body-less GET request is performed.

If you wish to see the intermediary requests/responses, then use the –all option:

1

$ http --follow --all pie.dev/redirect/3

To change the default limit of maximum 30 redirects, use the --max-redirects=<limit> option:

1

$ http --follow --all --max-redirects=2 pie.dev/redirect/3

Sessions

Use named sessions to make certain aspects of the communication persistent between requests to the same host:

1

$ http --session=logged-in -a username:password pie.dev/get API-Key:123

1

$ http --session=logged-in pie.dev/headers

Forms

Adding the –form, -f option for submitting forms:

Regular forms

1

$ http --form POST pie.dev/post name='John Smith'

1
2
3
4


POST /post HTTP/1.1
Content-Type: application/x-www-form-urlencoded; charset=utf-8

name=John+Smith

File upload forms

1
2
3
4


<form enctype="multipart/form-data" method="post" action="http://example.com/jobs">
    <input type="text" name="name" />
    <input type="file" name="cv" />
</form>

1

$ http -f POST pie.dev/post name='John Smith' cv@~/files/data.xml

Please note that @ is used to simulate a file upload form field, whereas =@ just embeds the file content as a regular text field value.

When uploading files, their content type is inferred from the file name. You can manually override the inferred content type:

1

$ http -f POST pie.dev/post name='John Smith' cv@'~/files/data.bin;type=application/pdf'

To perform a multipart/form-data request even without any files, use --multipart instead of --form:

1

$ http --multipart --offline example.org hello=world

HTTPS

Server SSL certificate verification

To skip the host’s SSL certificate verification, you can pass --verify=no (default is yes):

1

$ http --verify=no https://pie.dev/get

Custom CA bundle

You can also use --verify=<CA_BUNDLE_PATH> to set a custom CA bundle path:

1

$ http --verify=/ssl/custom_ca_bundle https://example.org

Client side SSL certificate

To use a client side certificate for the SSL communication, you can pass the path of the cert file with --cert:

1

$ http --cert=client.pem https://example.org

If the private key is not contained in the cert file, you may pass the path of the key file with --cert-key:

1

$ http --cert=client.crt --cert-key=client.key https://example.org

If the given private key requires a passphrase, HTTPie will automatically detect it and ask it through a prompt:

1
2


$ http --cert=client.pem --cert-key=client.key https://example.org
http: passphrase for client.key: ****

If you don’t want to see a prompt, you can supply the passphrase with the --cert-key-pass argument:

1

$ http --cert=client.pem --cert-key=client.key --cert-key-pass=my_password https://example.org

SSL version

Use the --ssl=<PROTOCOL> option to specify the desired protocol version to use. This will default to SSL v2.3 which will negotiate the highest protocol that both the server and your installation of OpenSSL support. The available protocols are ssl2.3, ssl3, tls1, tls1.1, tls1.2, tls1.3. (The actually available set of protocols may vary depending on your OpenSSL installation.)

1
2


Specify the vulnerable SSL v3 protocol to talk to an outdated server:
$ http --ssl=ssl3 https://vulnerable.example.org

SSL ciphers

You can specify the available ciphers with --ciphers. It should be a string in the OpenSSL cipher list format.

1

$ http --ciphers=ECDHE-RSA-AES128-GCM-SHA256 https://pie.dev/get

Note: these cipher strings do not change the negotiated version of SSL or TLS, they only affect the list of available cipher suites. To see the default cipher string, run http --help and see the --ciphers section under SSL.

Using file contents as values

1
2
3
4
5


$ http POST pie.dev/post \
    X-Data:@files/text.txt             # Read a header from a file
    token==@files/text.txt             # Read a query parameter from a file
    name=@files/text.txt               # Read a data field’s value from a file
    bookmarks:=@files/data.json        # Embed a JSON object from a file

GUI

1

$ paru -S httpie-desktop-bin

Table of Contents

CLI