Skip to content
Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

Java httpbin

Build Status Maven Central

A Java-based HTTP server that lets you locally test your HTTP client, retry logic, streaming behavior, timeouts, etc. with the endpoints of

This way, you can write tests without relying on an external dependency like


Java httpbin supports a subset of httpbin endpoints:

  • /ip Returns Origin IP.
  • /user-agent Returns user-agent.
  • /headers Returns headers.
  • /delete Returns DELETE data.
  • /get Returns GET data.
  • /patch Returns PATCH data.
  • /post Returns POST data.
  • /put Returns PUT data.
  • /anything Returns anything passed in request data.
  • /status/:code Returns given HTTP Status code.
  • /redirect/:n 302 Redirects n times.
  • /relative-redirect/:n 302 Redirects n times.
  • /absolute-redirect/:n 302 Absolute redirects n times.
  • /redirect-to?url=foo 302 Redirects to the foo URL.
  • /stream/:n Streams n lines of JSON objects.
  • /stream-bytes/:n?chunkSize=c&seed=s Streams n bytes.
  • /delay/:n Delays responding for min(n, 10) seconds.
  • /bytes/:n Generates n random bytes of binary data, accepts optional seed integer parameter.
  • /base64/:s Returns a base64 decoded :s input
  • /range/:s Return a subset of data based on Content-range header.
  • /cookies Returns the cookies.
  • /cookies/set?name=value Sets one or more simple cookies.
  • /cookies/delete?name Deletes one or more simple cookies.
  • /drip?numbytes=n&duration=s&delay=s&code=code Drips data over a duration after an optional initial delay, then optionally returns with the given status code.
  • /cache Returns 200 unless an If-Modified-Since or If-None-Match header is provided, when it returns a 304.
  • /cache/:n Sets a Cache-Control header for n seconds.
  • /etag Return 200 when If-Match or If-None-Match succeed.
  • /gzip Returns gzip-encoded data.
  • /deflate Returns deflate-encoded data.
  • /robots.txt Returns some robots.txt rules.
  • /deny Denied by robots.txt file.
  • /basic-auth/:user/:passwd Challenges HTTP Basic Auth.
  • /hidden-basic-auth/:user/:passwd Challenges HTTP Basic Auth and returns 404 on failure.
  • /html Returns some HTML.
  • /xml Returns some XML.
  • /image/png Returns page containing a PNG image.
  • /image/jpeg Returns page containing a JPEG image.


First add dependency to pom.xml:


Then add to your test code:

private URI httpBinEndpoint = URI.create("");
private final HttpBin httpBin = new HttpBin(httpBinEndpoint);

public void setUp() throws Exception {

    // reset endpoint to handle zero port
    httpBinEndpoint = new URI(httpBinEndpoint.getScheme(),
            httpBinEndpoint.getUserInfo(), httpBinEndpoint.getHost(),
            httpBin.getPort(), httpBinEndpoint.getPath(),
            httpBinEndpoint.getQuery(), httpBinEndpoint.getFragment());

public void tearDown() throws Exception {

public void test() throws Exception {
    URI uri = URI.create(httpBinEndpoint + "/status/200");
    HttpURLConnection conn = (HttpURLConnection) uri.toURL().openConnection();
    assert conn.getResponseCode() == 200;



Copyright (C) 2018-2019 Andrew Gaul
Copyright (C) 2015-2016 Bounce Storage

Licensed under the Apache License, Version 2.0


A Java-based HTTP server that lets you locally test your HTTP client, retry logic, streaming behavior, timeouts, etc. with the endpoints of





No packages published