Logo Httpbun

This is a service to help easily test the behaviour of HTTP clients like browsers, libraries, developer tools or anything else. Inspired by httpbin. I made this because httpbin lacked some things I needed, like:

  1. The /mix endpoint, and the Mixer.
  2. The /run endpoint, and the Runner.
  3. The /payload endpoint
  4. Allowing request body in /get endpoint.
  5. Accept any method in /headers and most other such endpoints.
  6. Not hiding some headers in responses.
  7. More practical handling of unescaped special characters in x-www-form-urlencoded payloads.

Canonical version is at httpbun.com. Also at https://self-signed-cert.httpbun.com that uses a self-signed HTTPS certificate.

★ Star this project on GitHub.

Endpoints

/get
/post
/put
/patch
/delete
Accepts GET/POST/... requests and responds with a JSON object with form body, query params, headers and a few other information about the request.
Examples 
curl httpbun.org/get
curl -X POST -d 'one=1' httpbun.org/post
curl -X POST -d '{"one": 1}' -H 'content-type:application/json' httpbun.org/post
curl -X PUT httpbun.org/put
curl -X PATCH httpbun.org/patch
curl -X DELETE httpbun.org/delete
/any
/any/{extraPath}
Acts like /get, /post etc., but works on any method, and any extra path after /any is also accepted.
/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' httpbun.org/headers
/payload
Responds with the same Content-Type header as the request and the body of the request as is.
Examples 
curl -H 'Content-Type: text/plain' -d 'plain body' httpbun.org/payload
curl -H 'Content-Type: application/json' -d '{"a": 1}' httpbun.org/payload

Authentication

/basic-auth/{username}/{password}
Requires basic authentication with username and password as the credentials.
Examples 
curl -H 'Authorization: Basic c2NvdHQ6dGlnZXI=' httpbun.org/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' httpbun.org/bearer
curl -H 'Authorization: Bearer expected_token' httpbun.org/bearer/expected_token
/digest-auth/{username}/{password}
/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 defaults to auth.

Client Details

/ip
/ip.txt
Responds with a JSON object with a single field, origin, with the client's IP Address 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 than can trigger XSS, in vulnerable places.
/robots.txt
Returns some robots.txt rules.
/base64
/base64/{encoded}
Decodes the encoded text with base64 encoding scheme. Defaults to SFRUUEJVTiBpcyBhd2Vzb21lciE=.
/bytes/{count}
Returns count random bytes in the response. The Content-Type header is set to application/octet-stream. The randomness is not cryptographically secure.
/delay/{seconds}
Respond with a delay of seconds seconds. The seconds parameter can be a positive integer or floating point number.
/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.

Redirects

/redirect
/redirect-to
Responds with a redirect to the URL given by the url query param. If a status query param is also given, it is used as the HTTP Status code in the response. Otherwise, 302 is used.
/redirect/{count}
/relative-redirect/{count}
Redirect count times. For example, /redirect/3 will redirect three times before settling on a response. The redirect URLs specified in the Location header will be relative URLs.
/absolute-redirect/{count}
Redirect count times. For example, /redirect/3 will redirect three times before settling on a response. The redirect URLs specified in the Location header will be absolute URLs.

Mix

/mix
Combine behaviour from multiple of other endpoints, into one. For example, if we want an endpoint with some response headers, as well as a specific status code, we can use: 
/mix/s=400/h=x-custom-header:some-value
The s= and h= are directives that /mix understands. Supported directives are:
  1. s: HTTP response status code.
  2. h: Set a response header, in the form name:value.
  3. c: Set a cookie, in the form name:value.
  4. r: Set a redirect URL. Uses status code 307. To change, use s= directive.
  5. b64: Set the response body to the base64 decoded value.
  6. t: The base64 decoded value of this, is rendered as a Golang text template, and the result is used as the response body.
  7. end: Takes no value, marks the end of directive processing. Path segment after this is ignored by Httpbun.

Learn more in the guide, and use the mixer for a UI to build these URLs.

Self Hosting

With Docker: docker run -p 80:80 sharat87/httpbun

From source, with task installed: task 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.
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 the /get endpoint will be available on /the-one/get. Similarly, all other endpoints are also prefixed with the value of this argument.

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: