httpbin — HTTP Request and Response Testing Service

Introduction

httpbin is a lightweight HTTP testing service that returns structured JSON responses reflecting the request it received. Originally created by Kenneth Reitz and now maintained by Postman Labs, it provides endpoints for every HTTP method, status code, authentication type, and content format. It serves as a reference implementation for testing HTTP clients and proxies.

What httpbin Does

• Echoes back request headers, query parameters, form data, and JSON payloads in a structured JSON response
• Provides endpoints that return specific HTTP status codes, redirect chains, and response delays for client testing
• Supports testing of authentication schemes including Basic Auth, Bearer Token, and Digest Auth
• Generates responses in various formats including JSON, HTML, XML, images, and binary data
• Offers streaming endpoints, chunked transfer encoding, and WebSocket echo for advanced protocol testing

Architecture Overview

httpbin is built on Flask, the Python WSGI micro-framework. Each endpoint is a Flask route that inspects the incoming request object and returns a JSON representation of its components. The application is stateless and requires no database or external dependencies. It can be deployed behind any WSGI server such as Gunicorn or uWSGI, and the official Docker image bundles everything for single-command deployment.

Self-Hosting & Configuration

• Deploy instantly with Docker using the official image from Docker Hub
• Run locally with Python: pip install httpbin and gunicorn httpbin:app
• No configuration files needed; the service is stateless and zero-config
• Place behind a reverse proxy like Nginx or Caddy for TLS termination in production
• Scale horizontally since every instance is identical and shares no state

Key Features

• Comprehensive endpoint coverage for all HTTP methods (GET, POST, PUT, PATCH, DELETE, OPTIONS)
• Programmable response delays via /delay/{n} for timeout testing
• Redirect chains via /redirect/{n} for testing redirect-following behavior
• Cookie setting and inspection endpoints for session testing
• Response inspection endpoints that return gzipped, deflated, or Brotli-compressed data

Comparison with Similar Tools

• Postman Echo — Cloud-hosted echo service by Postman; httpbin is fully self-hostable and open source
• Mocky — Generates custom mock endpoints via a web UI; httpbin provides fixed, predictable endpoints for standardized testing
• WireMock — Programmable mock server with request matching and stateful behavior; httpbin is simpler and purpose-built for echo testing
• RequestBin — Collects and inspects webhooks; httpbin echoes requests immediately rather than storing them
• JSONPlaceholder — Fake REST API for frontend prototyping; httpbin focuses on HTTP protocol testing rather than data simulation

FAQ

Q: Is there a public httpbin instance I can use? A: Yes. httpbin.org is the canonical public instance, though for production testing or high-volume use, self-hosting is recommended.

Q: Can I use httpbin to test file uploads? A: Yes. The /post endpoint accepts multipart form data and returns the uploaded file metadata in the response.

Q: Does httpbin support HTTPS? A: The public instance at httpbin.org serves over HTTPS. Self-hosted instances need a reverse proxy or WSGI server configured with TLS certificates.

Q: How do I test specific HTTP status codes? A: Use the /status/{code} endpoint. For example, GET /status/404 returns a 404 response, and /status/500 returns a 500.

Sources

• https://github.com/postmanlabs/httpbin
• https://httpbin.org