HTTPie API Client

What it is

HTTPie is a command-line HTTP client for interacting with web services and APIs, designed for human beings.

Installation

Linux

sudo apt update && sudo apt install httpie
# or
sudo dnf install httpie
# or
pip install --user httpie

macOS

brew install httpie
# or
pip install --user httpie

Windows

pip install --user httpie

Core Concepts

HTTPie simplifies HTTP requests by offering a more intuitive syntax than curl or wget. It distinguishes between different types of request elements:

• URL: The endpoint of the request.
• Parameters: Query string parameters appended to the URL (e.g., search==apple).
• Data: Request body, sent with POST, PUT, PATCH requests. Can be JSON, form-encoded, or raw text.
• Headers: Metadata sent with the request (e.g., Authorization:Bearer mytoken).
• Files: Uploading files as part of the request.

Commands / Usage

Making Basic Requests

# GET request to fetch a JSON API endpoint
http GET httpbin.org/get

# GET request with query parameters
http GET httpbin.org/get search==python version==3.9

# POST request with JSON data
http POST httpbin.org/post name=JohnDoe age:=30

# POST request with raw text data
http POST httpbin.org/post < request.txt

# PUT request with JSON data
http PUT httpbin.org/put id:=123 status='completed'

# DELETE request
http DELETE httpbin.org/delete id:=123

# HEAD request to get only headers
http HEAD httpbin.org/get

# OPTIONS request to see allowed methods
http OPTIONS httpbin.org/get

Sending Data

JSON Data

# Sending JSON object (keys prefixed with ':')
http POST httpbin.org/post name:="Alice" city:="Wonderland" age:=25

# Sending nested JSON object
http POST httpbin.org/post user:='{"name": "Bob", "id": 456}'

# Sending JSON array
http POST httpbin.org/post items:='["apple", "banana"]'

Form-Encoded Data

# Sending form-encoded data (keys without prefixes)
http POST httpbin.org/post username=testuser password=secret123

# Sending form-encoded data with explicit Content-Type
http --form POST httpbin.org/post username=testuser password=secret123

Raw Text Data

# Sending raw text from stdin
echo "This is my raw message." | http POST httpbin.org/post

# Sending raw text from a file
http POST httpbin.org/post < payload.txt

Uploading Files

# Uploading a file with a specific field name
http POST httpbin.org/post file_field@/path/to/your/image.jpg

# Uploading multiple files
http POST httpbin.org/post file1@/path/to/doc.pdf file2@/path/to/archive.zip

# Uploading a file with a custom filename
http POST httpbin.org/post avatar@/path/to/photo.png:custom_avatar.png

Authentication

# Basic Authentication
http --auth=user:password httpbin.org/basic-auth/user/password

# Bearer Token Authentication
http Authorization:'Bearer YOUR_ACCESS_TOKEN' httpbin.org/headers

# Digest Authentication
http --auth=user:password --auth-type=digest httpbin.org/digest-auth/auth/user/password

Headers

# Sending custom headers
http GET httpbin.org/headers X-My-Header:Value Accept:application/json

# Overriding default User-Agent
http --user-agent="MyAwesomeClient/1.0" httpbin.org/user-agent

Request Options

# Following redirects
http --follow httpbin.org/redirect/1

# Ignoring SSL certificate errors (use with caution)
http --verify=no https://self-signed.badssl.com/

# Setting a timeout for the request
http --timeout=5 httpbin.org/delay/3

# Replaying a request multiple times
http --repeat=5 httpbin.org/get

# Saving response to a file
http --download httpbin.org/image/png > image.png

# Saving response to a file with a specific name
http --download --output=saved_image.png httpbin.org/image/jpeg

Sessions

HTTPie can persist cookies and other session data between requests.

# Start a session
http --session=my_api_session POST httpbin.org/cookies/set/session_id/12345

# Make another request within the same session
http --session=my_api_session GET httpbin.org/cookies

Output Formatting

# Pretty-print JSON response (default for JSON)
http httpbin.org/json

# Raw output (no formatting)
http --raw httpbin.org/html

# Output only the response body
http --body httpbin.org/get

# Output only the response headers
http --headers httpbin.org/get

# Output only the status line
http --status httpbin.org/get

# Output request and response headers
http --verbose httpbin.org/get

Common Patterns

Authenticating with an API and fetching data

# Using a Bearer token for authentication
http Authorization:'Bearer abcdef12345' https://api.example.com/v1/users

Sending JSON data from a file

# POSTing a JSON payload defined in a file
http POST https://api.example.com/v1/items < item_data.json

Uploading a file and sending additional form data

# Uploading a profile picture and setting a user ID
http POST https://api.example.com/v1/profile/upload avatar@~/Pictures/profile.jpg user_id:=987

Chaining requests using sessions

# 1. Log in and get a session token
http --session=my_session POST https://auth.example.com/login username=testuser password=secret > /dev/null

# 2. Use the session to access a protected resource
http --session=my_session GET https://api.example.com/dashboard

Debugging API requests

# See the full request and response, including headers
http --verbose POST https://api.example.com/items name="New Item"

Interacting with APIs that require specific content types

# Sending XML data
http --headers Content-Type:application/xml POST https://api.example.com/xml_endpoint < data.xml

Gotchas

• JSON vs Form Data: Be mindful of how you prefix keys. key=value sends form-encoded data, while key:=value or key:="value" sends JSON data. If you intend to send JSON but forget the colon, HTTPie might send it as form data, leading to unexpected server behavior.
• := vs :: The := operator is used for JSON values that should be treated as raw JSON (e.g., nested objects or arrays). The : operator is for JSON string values, and HTTPie will automatically enclose them in quotes.
• SSL Verification: Disabling SSL verification (--verify=no) is convenient for testing with self-signed certificates but is a security risk in production environments.
• File Uploads: When uploading files with @, ensure the path is correct. If you need to specify a custom filename in the request, use field@path/to/file:custom_filename.ext.
• Sessions: Session files are stored in ~/.httpie/sessions/. If you’re having issues with session persistence, check the contents of these files or delete them to start fresh.
• Default Method: If no HTTP method is explicitly provided, HTTPie defaults to GET. For POST requests, you must specify POST.