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 the /mix endpoint, the /payload endpoint, not ignore request body in /get, accepting any method in most endpoints, not hiding some headers, etc.

★ 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 oof.ooo/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' oof.ooo/post
curl -X POST -d '{"one": 1}' -H 'content-type:application/json' oof.ooo/post
curl -X PUT oof.ooo/put
curl -X PATCH oof.ooo/patch
curl -X DELETE oof.ooo/delete
/any
/any/{...}
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' oof.ooo/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' oof.ooo/payload
curl -H 'Content-Type: application/json' -d '{"a": 1}' oof.ooo/payload

Authentication

/basic-auth/{username}/{password}
Requires basic authentication with username and password as the credentials.
Examples 
curl -H 'Authorization: Basic c2NvdHQ6dGlnZXI=' oof.ooo/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' oof.ooo/bearer
curl -H 'Authorization: Bearer expected_token' oof.ooo/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 pseudo-randomness algorithm is not to be considered as cryptographically secure.
/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.

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.

Use the mixer for a UI to generate 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.

Differences from Httpbin

This is a non-exhaustive list of differences from httpbin.

  1. Not all endpoints are available. If you need something, please open an issue on GitHub.
  2. Almost all endpoints work with any HTTP method. Notable exceptions are the method endpoints themselves, i.e., /get, /post, etc.
  3. The bytes returned by /range are not the same as those from httpbin.
  4. 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.
  5. No hidden headers. All headers are returned in endpoints that send headers in response, like /headers. See list of hidden headers on httpbin.
  6. 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: