Tiny JSON echo server for testing HTTP clients

When a request does not do what you expect, the fastest check is to send it to a server that shows you exactly what arrived. This script is that server. It needs only Python 3.7 or newer and listens on 127.0.0.1, so nothing outside your machine can reach it.

The script

#!/usr/bin/env python3
"""Tiny JSON echo server for testing HTTP clients. Standard library only."""
import json
import sys
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
from urllib.parse import urlsplit, parse_qs

MAX_BODY = 1_000_000  # bytes; larger bodies get 413


class EchoHandler(BaseHTTPRequestHandler):
    def _send_json(self, status, payload):
        body = json.dumps(payload, indent=2).encode("utf-8")
        self.send_response(status)
        self.send_header("Content-Type", "application/json; charset=utf-8")
        self.send_header("Content-Length", str(len(body)))
        self.end_headers()
        if self.command != "HEAD":
            self.wfile.write(body)

    def _handle(self):
        url = urlsplit(self.path)

        # /status/404 answers with that status code
        parts = url.path.strip("/").split("/")
        if len(parts) == 2 and parts[0] == "status" and parts[1].isdigit():
            code = int(parts[1])
            if 200 <= code <= 599:
                self._send_json(code, {"status": code})
                return

        length = int(self.headers.get("Content-Length") or 0)
        if length > MAX_BODY:
            self.close_connection = True
            self._send_json(413, {"error": "body too large", "limit": MAX_BODY})
            return
        raw = self.rfile.read(length) if length else b""

        body = raw.decode("utf-8", errors="replace")
        if "json" in (self.headers.get("Content-Type") or ""):
            try:
                body = json.loads(raw or b"null")
            except json.JSONDecodeError as exc:
                self._send_json(400, {"error": "invalid JSON", "detail": str(exc)})
                return

        self._send_json(200, {
            "method": self.command,
            "path": url.path,
            "query": parse_qs(url.query),
            "headers": dict(self.headers),
            "body": body,
        })

    do_GET = do_POST = do_PUT = do_PATCH = do_DELETE = do_HEAD = _handle


if __name__ == "__main__":
    port = int(sys.argv[1]) if len(sys.argv) > 1 else 8765
    server = ThreadingHTTPServer(("127.0.0.1", port), EchoHandler)
    print(f"Echo server on http://127.0.0.1:{port}  (Ctrl+C to stop)")
    try:
        server.serve_forever()
    except KeyboardInterrupt:
        pass
    finally:
        server.server_close()

Running it

python3 echo_server.py          # listens on port 8765
python3 echo_server.py 9000     # or pick a port

In a second terminal, send it something:

curl -s --json '{"hello": "world"}' 'http://127.0.0.1:8765/items?debug=1'
curl -s -i http://127.0.0.1:8765/status/503

The first command returns a JSON document listing the method, path, parsed query string, every header curl sent, and the parsed body. The second returns a 503 status so you can check how your client handles errors. Stop the server with Ctrl+C.

What it is good for

• Checking that your client really sends the Authorization, Content-Type, or custom headers you think it does.
• Seeing whether a body is JSON, form data, or plain text after a library has encoded it.
• Testing retry and error handling: /status/429, /status/500, and friends return those codes.
• Reproducing a 413 by sending more than one megabyte, or a 400 by sending invalid JSON with a JSON content type.

How it works

BaseHTTPRequestHandler parses the request line and headers for you and calls a method named after the HTTP verb, such as do_GET. The script points all the verbs at one function. The body is read from rfile using the Content-Length header, which is also how the size limit is enforced before reading. ThreadingHTTPServer handles each connection in its own thread, so one slow client does not block others.

This is a debugging tool, not a production server. It has no TLS, does not support chunked request bodies, and prints request headers back, which may include tokens. Keep it bound to localhost.