head

Matches requests with HTTP method HEAD.

Signature

def head: Directive0

Description

This directive filters the incoming request by its HTTP method. Only requests with method HEAD are passed on to the inner route. All others are rejected with a MethodRejectionMethodRejection, which is translated into a 405 Method Not Allowed response by the default RejectionHandler.

Note

Apache Pekko HTTP can handle HEAD requests transparently by dispatching a GET request to the handler and stripping off the result body. See the pekko.http.server.transparent-head-requests setting for how to enable this behavior.

Note

The response body is stripped off, but the Content-Length header is still rendered when the entity declares a non-zero length, so that clients can learn the size of the resource without fetching it. Entities without a known length (Chunked, CloseDelimited) and empty entities render no Content-Length; if you want to answer a HEAD request with the size of the hypothetical GET response without producing the bytes, complete with HttpEntity.Default(contentType, length, Source.empty).

Example

Scala
sourceval route = head { complete("This is a HEAD request.") }

// tests:
Head("/") ~> route ~> check {
  responseAs[String] shouldEqual "This is a HEAD request."
}
Java
sourceimport static org.apache.pekko.http.javadsl.server.Directives.complete;
import static org.apache.pekko.http.javadsl.server.Directives.head;

final Route route = head(() -> complete("This is a HEAD request."));

testRoute(route).run(HttpRequest.HEAD("/")).assertEntity("This is a HEAD request.");
1.4.1