Logo Httpbun

This is a service to help easily test the behaviour of HTTP clients like browsers, libraries, developer tools or anything else. Heavily inspired by the httpbin project. Canonical version available at httpbun.com, currently mirrored at httpbun.org as well.

★ Star this project on GitHub.

Endpoints

/get
Accepts GET requests and responds with a JSON object with query params, headers and a few other information about the request.
Examples 
curl echo.basistheory.com/get
/post
/put
/patch
/delete
Accepts POST requests and responds with a JSON object with form body, query params, headers and a few other information about the request. There's also /put, /patch and /delete endpoints that behave similarly.
Examples 
curl -X POST -d 'one=1' echo.basistheory.com/post
curl -X POST -d '{"one": 1}' -H 'content-type:application/json' echo.basistheory.com/post
curl -X PUT echo.basistheory.com/put
curl -X PATCH echo.basistheory.com/patch
curl -X DELETE echo.basistheory.com/delete
/headers
Responds with a JSON object with a single field, headers which is an object of all the headers in the request, as keys and values. If a header repeats in the request, then its values are concatenated with a comma and treated as a single header value.
Examples 
curl -H 'x-custom: custom header value' echo.basistheory.com/headers

Authentication

/basic-auth/{username}/{password}
Requires basic authentication with username and password as the credentials.
Examples 
curl -H 'Authorization: Basic c2NvdHQ6dGlnZXI=' echo.basistheory.com/basic-auth/scott/tiger
/bearer
/bearer/{expectedToken}
Requires bearer authentication. Which needs an Authorization header in the request, that takes the form Bearer some-auth-token-here. If no expectedToken is given, any token will be treated as valid. If no Authorization header is present in the request, this results in a 401 response.
Examples 
curl -H 'Authorization: Bearer auth_token_here' echo.basistheory.com/bearer
curl -H 'Authorization: Bearer expected_token' echo.basistheory.com/bearer/expected_token
/digest-auth/{qop}/{username}/{password}
Digest authentication. The endpoint /digest-auth/auth/scott/tiger requires to be authenticated with the credentials scott and tiger as username and password. The implementation is based on this example from Wikipedia. The value of qop is usually equal to auth.

Client Details

/ip
Responds with a JSON object with a single field, origin, with the client's IP Address for value.
/user-agent
Responds with a JSON object with a single field, user-agent, with the client's user agent (as present in the User-Agent header) for value.

Caching

/cache
If the request contains an If-Modified-Since or If-None-Match header, returns a 304 response. Otherwise, it behaves the same as /get for GET requests, /post for POST requests, etc.
/cache/{age}
Sets a Cache-Control header for age seconds.
/etag/{etag}
Assumes the resource has the given etag and responds to If-None-Match and If-Match headers appropriately.

Client Tuned Response

/status/{codes}
Responds with the HTTP status as given by codes. It can be a comma-separated list of multiple status codes, of which a random one is chosen for the response.
/response-headers
/respond-with-headers
Sends given query parameters as headers in the response. For example, in the response from /response-headers?one=two, there is a header called One, whose value is two. The response body contains all the headers again, in the form of a JSON object. (This JSON object in the response should be considered deprecated, and may be removed in the future.)
/deny
Returns page denied by robots.txt rules.
/html
Returns a small HTML document, sans CSS, sans Javascript. The same response is returned every time.
/json
Returns a small JSON object. The same response is returned every time.
/robots.txt
Returns some robots.txt rules.
/xml
Returns a small XML document. The same response is returned every time.
/delay/{seconds}
Respond with a delay of seconds seconds. The seconds parameter has to be an integer currently. Fractional delays are not yet supported.
/drip
/drip-lines
Drips data over a duration, with an interval between each piece of data. The piece of data is the * character. The following query params can be used to configure this endpoint: When using /drip-lines, a newline character is written after every piece of data.
Returns an HTML document with count links, which in turn respond with HTML documents with links again. You mostly want to use the first version (i.e., without offset).
/range/{count}
Returns count random bytes, that are generated with the same random seed every time. The value of count is capped to 1000.
/cookies
Returns cookie data from the request headers.
/cookies/set
Sets cookies for all given query params.
/cookies/set/{name}/{value}
Set the cookie name to value.
/cookies/delete
Returns a response that will delete cookies in the browser. Cookies to be deleted should be given as query params. The values of these query params are ignored and can be empty.

Anything

/anything
/anything/{...}
Acts like /get, /post etc., but works on any method.

Self Hosting

With Docker: docker run -p 8008:80 ghcr.io/sharat87/httpbun

With source: make run

Configuration

--bind
The network address to bind the server to. Defaults to localhost:3090, which configures the server to listen on TCP port 3090 on localhost. It can also be set to unix//var/run/httpbun.sock, which configures the server to listen on the Unix socket located at /var/run/httpbun.sock.
This option can also be set with the HTTPBUN_BIND environment variable.
--path-prefix
Sets a path prefix for all the paths in Httpbun. For example, if this is set to /the-one, then Httpbun's /get endpoint will be available on /the-one/get instead. Similarly, all other endpoints are also prefixed with the value of this argument.
HTTPBUN_ALLOW_HOSTS
A comma separated list of hosts at which this instance will accept connections. Defaults to empty, which means it will allow any. An example: httpbun.com,httpbun.org.
HTTPBUN_FORCE_HTTPS
If set to 1, only accept connections coming in as https. By default, https is not forced.
HTTPBUN_INFO_ENABLED
If set to 1, the endpoint /info will be available, which responds with various server information. By default, /info returns a 404 Not Found response.

Differences from Httpbin

  1. Not all endpoints are available. If you need something, please open an issue on GitHub.
  2. Headers are always in their canonical representation. That is, the header X-One is always represented as X-One, and never as x-one or any other casing. This may change in the future.
  3. Almost all endpoints work with any HTTP method. Notable exceptions are the method endpoints themselves, i.e., /get, /post, etc.
  4. The bytes returned by /range are not the same as those from httpbin.
  5. HTML characters are escaped in JSON output. This shouldn't cause much affect, usually, but is good to know. Reason and details.
  6. Multipart-form data payloads without a boundary set, will respond with a 400 Bad Request error, instead of responding with a success, and empty body details like httpbin.
  7. No hidden headers. All headers are returned in endpoints that send headers in response, like /headers. This is a feature of httpbin, but not httpbun. See this list on httpbin.
  8. Written in Go.

License

Httpbun is distributed with the Apache-2.0 License. Please refer to the LICENSE and NOTICE files present in the source distribution of this project.

Credits

  1. httpbin. This project might not have existed, if not for httpbin.
  2. Go's excellent documentation. This project might've taken a hell of a lot longer, if not for Go's docs.

The bun icon was generated using the following graphics from Twitter Twemoji: