HTTP Request and Response Service

0.10.2 · active · verified Wed Apr 15

httpbin is an open-source HTTP request and response service, implemented in Python using Flask. It provides various endpoints that echo back client requests, return specific status codes, headers, or dynamic data, making it invaluable for testing HTTP clients, debugging webhooks, and understanding HTTP protocol concepts. The current version, 0.10.2, is actively maintained by the Python Software Foundation (PSF) and has seen several recent releases, including a major fork from its original maintainer due to inactivity.

Warnings

gotcha The `httpbin` PyPI package (maintained by PSF) is a fork and is NOT the backend for the public service `httpbin.org` (which is run by Postman Labs). Users often confuse the two, leading to potential discrepancies between local test environments and public service behavior.
Fix: Be aware of the distinction. For critical testing, consider running a local instance of httpbin from the PSF package instead of relying on the public httpbin.org service.
gotcha Relying on the public `httpbin.org` service for automated tests can lead to intermittent failures due to network latency, server load, or unexpected changes in `httpbin.org`'s responses (e.g., occasional HTTP vs. HTTPS inconsistencies).
Fix: For robust and reliable testing, it is highly recommended to run a local `httpbin` instance (using the PyPI package) within your testing environment, for example, using `pytest-httpbin` or by deploying it with Gunicorn.
gotcha To run `httpbin` as a standalone application, you must install it with the `mainapp` extra (e.g., `pip install 'httpbin[mainapp]'`). A basic `pip install httpbin` might not include all necessary dependencies for direct execution or WSGI deployment.
Fix: Always install with `pip install 'httpbin[mainapp]'` if you intend to run it as a service or application. If using Gunicorn, ensure Gunicorn is also installed separately.

Install

pip install httpbin Install base package
pip install 'httpbin[mainapp]' Install with main application dependencies

Imports

app
```
from httpbin import app
```
Used when running httpbin as a WSGI application via a server like Gunicorn.

Quickstart

To use httpbin, you typically run it as a WSGI application. The most common way is with a WSGI server like Gunicorn, which serves the `httpbin:app` object. For development or quick testing, you can also run it directly as a module. The provided code includes instructions for both running the service and a Python example (using the 'requests' library) demonstrating how to interact with an httpbin instance, typically the public httpbin.org service.

import os

# To run httpbin as a standalone WSGI application using Gunicorn:
# 1. Ensure you have httpbin installed with the 'mainapp' extra:
#    pip install 'httpbin[mainapp]' gunicorn
# 2. Run the following command in your terminal:
#    gunicorn httpbin:app

# Alternatively, for a simple direct run (for development/testing):
# 1. Ensure httpbin is installed:
#    pip install httpbin
# 2. Run the following command in your terminal:
#    python -m httpbin.core

# Example of interacting with a running httpbin instance (using requests library):
# (This code is for demonstration, it interacts with httpbin.org, not your local instance)
import requests

base_url = "https://httpbin.org"

# Make a GET request and inspect the response
response_get = requests.get(f"{base_url}/get?key=value")
print(f"GET Status: {response_get.status_code}")
print(f"GET JSON: {response_get.json()['args']}")

# Make a POST request with JSON data
post_data = {"name": "test", "id": 123}
response_post = requests.post(f"{base_url}/post", json=post_data)
print(f"POST Status: {response_post.status_code}")
print(f"POST JSON: {response_post.json()['json']}")

view raw JSON →