Apache HTPP Client Notes

Russell Bateman
September 2008
last update:

Some ill-organized notes for the Apache HTTP client, Java classes HttpClient, HttpStatus, etc. For the new Java client, see here.


HttpStatus error status functional ranges

A refined suggestion for HTTP status codes
200 Success
204 There's no content, but the object is there
300 Requires further deliberation (effort)
304 What you've got is the latest
400 Caller is in error
420 Too many requests: use instead of 503 to disambiguate between throttling and simply unavailable
500 Server code or state is in error
503 Throttling; do this if by processing request, you endanger the application's up state

Error status descriptions

I don't know how old this information is that I've ripped off here. See also http://en.wikipedia.org/wiki/List_of_HTTP_status_codes.

The following are not errors
100 Continue Continue with partial request. 1.1
101 Switching protocols Server will comply with Upgrade header and change to different protocol. 1.1
200 OK Everything's fine; document follows for GET and POST requests. This is the default at well maintained servers. 1.0
201 Created Server created a document; the Location header indicates its URL. 1.0
202 Accepted Request is being acted upon, but processing is not completed. 1.0
203 Non-authoritative information Document is being returned normally, but some of the response headers might be incorrect since a document copy is being used. 1.1
204 No content No new document; browser should continue to display previous document. This is a useful if the user periodically reloads a page and you can determine that the previous page is already up to date. However, this does not work for pages that are automatically reloaded via the Refresh response header or the equivalent header, since returning this status code stops future reloading. JavaScript-based automatic reloading could still work in such a case, though. 1.0
205 Reset content No new document, but browser should reset the document view, clearing cgi form fields etc. 1.1
206 Partial content Client sent a partial request with a range header, and server has fulfilled it. 1.1
The following aren't exactly errors
300 Multiple choices Document requested can be found several places; they 'll be listed in the returned document. If server has a preferred choice, it should be listed in the Location response header. 1.0
301 Moved permanently Requested document is elsewhere, and the URL for it is given in the Location response header. Browsers should automatically follow the link to the new URL. 1.0
302 Found Similar to 301, except that the new URL should be interpreted as a temporary replacement, not a permanent one. The message was "Moved Temporarily" in HTTP 1.0. Browsers should automatically follow the link to the new URL. This status code is sometimes used interchangeably with 301. On a request for http://domain/path missing the trailing slash, some servers will send 301 and others will send 302. Technically, browsers are only supposed to automatically follow the redirection if the original request was GET. See the 307 header for details. 1.0
303 See other Like 301 and 302, except that if the original request was POST, the redirected document (given in the Location header) should be retrieved via GET. 1.1
304 Not modified Client has a cached document and performed a conditional request (usually by supplying an If-Modified-Since header indicating that it only wants documents newer than a specified date). This tells client that the old, cached document should still be used. 1.0
305 Use proxy Requested document should be retrieved via the proxy listed in Location header. 1.1
307 Temporary redirect This is identical to 302 ("Found" or "Temporarily Moved"). It was added to 1.1 since many browsers erroneously followed the redirection on a 302 response even if the original message was a POST, even though it really ought to have followed the redirection of a POST request only on a 303 response. This response is intended to be unambigously clear: follow redirected GET and POST requests in the case of 303 responses, only follow the redirection for GET requests in the case of 307 responses. 1.1
The following are certainly errors
400 Bad request The request contained a syntax error and was not understood. 1.0
401 Unauthorized Client tried to access password-protected page without proper authorization. Response should include a WWW-Authenticate header that the browser would use to pop up a username/password dialog box, which then comes back via the Authorization header. 1.0
403 Forbidden Resource is not available, regardless of authorization. Often the result of bad file or directory permissions on the server. 1.0
404 Not found No resource could be found at that address. This is the standard "no such page" response. Browsers and servers a like usually have elaborate default pages ready for this status, with useless advice. 1.0
405 Method not allowed The request method (GET, POST, HEAD, DELETE, PUT, TRACE, etc.) was not allowed for the requested resource. 1.1
406 Not acceptable Resource indicated generates a MIME type incompatible with that specified by the client via its Accept header. 1.1
407 Proxy authentication required Similar to 401, but proxy server must return a Proxy-Authenticate header. 1.1
408 Request timeout The client took too long to send the request. 1.1
409 Conflict Usually associated with PUT requests; used for situations such as trying to upload an incorrect version of a file. 1.1
410 Gone Document is gone; no forwarding address known. Differs from 404 in that the document is known to be permanently gone in this case, not just unavailable for unknown reasons as with 404. 1.1
411 Length required Server cannot process request unless client sends a Content-Length header. 1.1
412 Precondition failed Some precondition specified in the request headers was false. 1.1
413 Request entity too large The requested document is bigger than the server can handle now. If the server thinks it can handle it later, it should include a Retry-After header. 1.1
414 Request URI too long The URI is too long. 1.1
415 Unsupported media type The request is in an unknown format. 1.1
416 Requested range not satisfiable Client included an unsatisfiable Range header in the request. 1.1
417 Expectation failed Value in the Expect request header could not be met. 1.1
500 Internal server error Generic "server is confused" message. It is often the result of CGI programs or servlets that crash or return improperly formatted headers. 1.0
501 Not implemented Server doesn't support functionality to fulfill request. Used, for example, when client issues an advanced command like PUT. 1.0
502 Bad gateway Used by servers that act as proxies or gateways; indicates that initial server got a bad response from the remote server. 1.0
503 Service unavailable Server cannot respond due to maintenance or overloading. For example, a servlet might return this header if some thread or database connection pool is currently full. Server may supply a Retry-After header. 1.0
504 Gateway timeout Used by servers that act as proxies or gateways; indicates that initial server didn't get a response from the remote server in time. 1.1
505 HTTP version not supported

Getting the response...

Method getResponseBody will return a byte array containing the data in the response body. However, this is not always the way data is returned. The HEAD method does not use this and I have yet to find out why or how it does it otherwise.

Other options, with caveat, are:


The HEAD method...

I'm figuring out how to get the metadata back using the HEAD method since the HEAD method eschews passing information back in the response body.

304 Not modified

"Use the local copy if you cached it." Apparently, this is often seen when using the HEAD method, rather than the GET method. Nevertheless, HCAP appears to pass back 200 OK.


HTTP header information...

How does HTTPS work?

At a shallow level, this is how it works:

  1. Client sends a message initiating the connection.
  2. Server sends its certificate in reply to the client.
  3. Client verifies the certificate using the certificate issued by the trusted authority.
  4. Server sends the request for the client's certificate.
  5. Client sends its certificate to the server.
  6. Server verifies the client's certificate.
  7. Server and the client exchange the master secret which is used during the encryption of data.
  8. A connection is established.



The "new" Java client...

See also Baeldung: Exploring the New HTTP Client in Java (9).


Simplest HTTP program 
import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class ReadWebPage
{
  public static void main( String[] args ) throws IOException, InterruptedException
  {
    HttpClient             client   = HttpClient.newHttpClient();
    HttpRequest            request  = HttpRequest.newBuilder()
                                      .uri( new URI( "http://www.slackware.com/" ) )
                                      .GET()
                                      .build();
    HttpResponse< String > response = client.send( request, HttpResponse.BodyHandlers.ofString() );
    int                    status   = response.statusCode();

    System.out.println( status + ": " + response.body() );
  }
}

Simplest HTTP program with POST 
import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class PostToWeb
{
  public static void main( String[] args ) throws IOException, InterruptedException
  {
    HttpClient  client              = HttpClient.newHttpClient();
    HttpRequest request             = HttpRequest.newBuilder()
                                      .uri( new URI( /* URL of some service */ ) )
                                      .headers( "Content-Type", "application/xml" )
                                      .headers( "Accept", "application/xml" )
                                      .POST( HttpRequest.BodyPublishers.ofString( PAYLOAD ) )
                                      .build();
    HttpResponse< String > response = client.send( request, HttpResponse.BodyHandlers.ofString() );
    int                    status   = response.statusCode();

    System.out.println( status + ": " + response.body() );
  }
}