Predefined Directives (alphabetically)

Directive Description
alwaysCache Wraps its inner Route with caching support using the given CacheCache implementation and the in-scope keyer function.
attribute Extracts the value of the request attribute with a given key
authenticateBasic Wraps the inner route with Http Basic authentication support using a given Authenticator[T]Authenticator<T>
authenticateBasicAsync Wraps the inner route with Http Basic authentication support using a given AsyncAuthenticator[T]AsyncAuthenticator<T>
authenticateBasicPF Wraps the inner route with Http Basic authentication support using a given AuthenticatorPF[T]AuthenticatorPF<T>
authenticateBasicPFAsync Wraps the inner route with Http Basic authentication support using a given AsyncAuthenticatorPF[T]AsyncAuthenticatorPF<T>
authenticateOAuth2 Wraps the inner route with OAuth Bearer Token authentication support using a given AuthenticatorPF[T]AuthenticatorPF<T>
authenticateOAuth2Async Wraps the inner route with OAuth Bearer Token authentication support using a given AsyncAuthenticator[T]AsyncAuthenticator<T>
authenticateOAuth2PF Wraps the inner route with OAuth Bearer Token authentication support using a given AuthenticatorPF[T]AuthenticatorPF<T>
authenticateOAuth2PFAsync Wraps the inner route with OAuth Bearer Token authentication support using a given AsyncAuthenticatorPF[T]AsyncAuthenticatorPF<T>
authenticateOrRejectWithChallenge Lifts an authenticator function into a directive
authorize Applies the given authorization check to the request
authorizeAsync Applies the given asynchronous authorization check to the request
cache Wraps its inner Route with caching support using the given CacheCache implementation and the in-scope keyer function.
cachingProhibited Passes only requests that explicitly forbid caching with a Cache-Control header with either a no-cache or max-age=0 setting.
cancelRejection Adds a TransformationRejectionTransformationRejection cancelling all rejections equal to the given one to the rejections potentially coming back from the inner route.
cancelRejections Adds a TransformationRejectionTransformationRejection cancelling all matching rejections to the rejections potentially coming back from the inner route
checkSameOrigin Checks that the request comes from the same origin
complete Completes the request using the given arguments
completeOrRecoverWith “Unwraps” a Future[T]CompletionStage<T> and runs the inner route when the future has failed with the error as an extraction of type Throwable
completeWith Uses the marshaller for a given type to extract a completion function
conditional Wraps its inner route with support for conditional requests as defined by RFC 7232
cookie Extracts the HttpCookieHttpCookie with the given name
cors Wrapps its inner route with CORS handling
decodeRequest Decompresses the request if it is gzip or deflate compressed
decodeRequestWith Decodes the incoming request using one of the given decoders
delete Rejects all non-DELETE requests
deleteCookie Adds a Set-Cookie response header expiring the given cookies
encodeResponse Encodes the response with the encoding that is requested by the client via the Accept-Encoding header (NoCoding, Gzip and Deflate)
encodeResponseWith Encodes the response with the encoding that is requested by the client via the Accept-Encoding header (from a user-defined set)
entity Extracts the request entity unmarshalled to a given type
extract Extracts a single value using a RequestContext => TFunction<RequestContext, T> function
extractDataBytes Extracts the entities data bytes as a stream Source<ByteString, ?>Source[ByteString, _]
extractClientIP Extracts the client’s IP from either the X-Forwarded-, Remote-Address or X-Real-IP header
extractCredentials Extracts the potentially present HttpCredentialsHttpCredentials provided with the request’s AuthorizationAuthorization header
extractExecutionContext Extracts the ExecutionContext from the RequestContextRequestContext
extractMatchedPath Extracts the already matched path from the RequestContextRequestContext
extractMaterializer Extracts the MaterializerMaterializer from the RequestContextRequestContext
extractHost Extracts the hostname part of the Host request header value
extractLog Extracts the LoggingAdapterLoggingAdapter from the RequestContextRequestContext
extractMethod Extracts the request method
extractOfferedWsProtocols Extract the list of websocket subprotocols offered by the client in the Sec-WebSocket-Protocol header if this is a websocket request and otherwise rejects with an ExpectedWebSocketRequestRejectionExpectedWebSocketRequestRejection
extractParserSettings Extracts the ParserSettingsParserSettings from the RequestContextRequestContext
extractRequest Extracts the current HttpRequestHttpRequest instance
extractRequestContext Extracts the RequestContextRequestContext itself
extractRequestEntity Extracts the RequestEntityRequestEntity from the RequestContextRequestContext
extractScheme Extracts the URI scheme from the request
extractSettings Extracts the RoutingSettingsRoutingSettings from the RequestContextRequestContext
extractUnmatchedPath Extracts the yet unmatched path from the RequestContextRequestContext
extractUpgradeToWebSocket Extract the UpgradeToWebSocketUpgradeToWebSocket header if existent and otherwise rejects with an ExpectedWebSocketRequestRejectionExpectedWebSocketRequestRejection
extractUri Extracts the complete request URI
failWith Bubbles the given error up the response chain where it is dealt with by the closest handleExceptions directive and its ExceptionHandlerExceptionHandler
fileUpload Provides a stream of an uploaded file from a multipart request
fileUploadAll Provides streams of all uploaded files from a multipart request
formField Extracts an HTTP form field (of Content-Type application/x-www-form-urlencoded or multipart/form-data) from the request
formFieldMap Extracts a number of HTTP form field (of Content-Type application/x-www-form-urlencoded or multipart/form-data) from the request as a Map[String, String]Map<String, String>
formFieldMultiMap Extracts a number of HTTP form field (of Content-Type application/x-www-form-urlencoded or multipart/form-data) from the request as a Map[String, List[String]]Map<String, List<String>>
formFields Extracts a number of HTTP form field (of Content-Type application/x-www-form-urlencoded or multipart/form-data) from the request
formFieldSeq Extracts a number of HTTP form field (of Content-Type application/x-www-form-urlencoded or multipart/form-data) from the request as a Seq[(String, String)]List<Map.Entry<String, String>>
get Rejects all non-GET requests
getFromBrowseableDirectories Serves the content of the given directories as a file-system browser, i.e. files are sent and directories served as browseable listings
getFromBrowseableDirectory Serves the content of the given directory as a file-system browser, i.e. files are sent and directories served as browseable listings
getFromDirectory Completes GET requests with the content of a file underneath a given file-system directory
getFromFile Completes GET requests with the content of a given file
getFromResource Completes GET requests with the content of a given class-path resource
getFromResourceDirectory Completes GET requests with the content of a file underneath a given “class-path resource directory”
handleExceptions Transforms exceptions thrown during evaluation of the inner route using the given ExceptionHandlerExceptionHandler
handleRejections Transforms rejections produced by the inner route using the given RejectionHandler
handleWebSocketMessages Handles websocket requests with the given handler and rejects other requests with an ExpectedWebSocketRequestRejectionExpectedWebSocketRequestRejection
handleWebSocketMessagesForOptionalProtocol Handles websocket requests with the given handler if the subprotocol matches and rejects other requests. If the subprotocol parameter is Noneempty any WebSocket request is accepted..
handleWebSocketMessagesForProtocol Handles websocket requests with the given handler if the subprotocol matches and rejects other requests with an ExpectedWebSocketRequestRejectionExpectedWebSocketRequestRejection or an UnsupportedWebSocketSubprotocolRejectionUnsupportedWebSocketSubprotocolRejection.
handleWith Completes the request using a given function
head Rejects all non-HEAD requests
headerValue Extracts an HTTP header value using a given HttpHeader => Option[T]Function<HttpHeader, Optional<T>> function
headerValueByName Extracts the value of the first HTTP request header with a given name
headerValueByType Extracts the first HTTP request header of the given type
headerValuePF Extracts an HTTP header value using a given PartialFunction[HttpHeader, T]]PartialFunction<HttpHeader, T>
host Rejects all requests with a non-matching host name
ignoreTrailingSlash Retries the inner route adding (or removing) the trailing slash in case of empty rejections
listDirectoryContents Completes GET requests with a unified listing of the contents of all given file-system directories
logRequest Produces a log entry for every incoming request
logRequestResult Produces a log entry for every incoming request and RouteResultRouteResult
logResult Produces a log entry for every RouteResultRouteResult
mapInnerRoute Transforms its inner RouteRoute with a Route => RouteUnaryOperator<Route> function
mapRejections Transforms rejections from a previous route with an immutable.Seq[Rejection] => immutable.Seq[Rejection]UnaryOperator<List<Rejection>> function
mapRequest Transforms the request with an HttpRequest => HttpRequestUnaryOperator<HttpRequest> function
mapRequestContext Transforms the RequestContextRequestContext with a RequestContext => RequestContextUnaryOperator<RequestContext> function
mapResponse Transforms the response with an HttpResponse => HttpResponseUnaryOperator<HttpResponse> function
mapResponseEntity Transforms the response entity with an ResponseEntity => ResponseEntityUnaryOperator<ResponseEntity> function
mapResponseHeaders Transforms the response headers with an immutable.Seq[HttpHeader] => immutable.Seq[HttpHeader]UnaryOperator<List<HttpHeader>> function
mapRouteResult Transforms the RouteResultRouteResult with a RouteResult => RouteResultUnaryOperator<RouteResult> function
mapRouteResultFuture Transforms the RouteResultRouteResult future with a Future[RouteResult] => Future[RouteResult]UnaryOperator<CompletionStage<RouteResult>> function
mapRouteResultPF Transforms the RouteResultRouteResult with a PartialFunction[RouteResult, RouteResult]PartialFunction<RouteResult, RouteResult>
mapRouteResultWith Transforms the RouteResultRouteResult with a RouteResult => Future[RouteResult]Function<RouteResult, CompletionStage<RouteResult>> function
mapRouteResultWithPF Transforms the RouteResultRouteResult with a PartialFunction[RouteResult, Future[RouteResult]]PartialFunction<RouteResult, CompletionStage<RouteResult>>
mapSettings Transforms the RoutingSettingsRoutingSettings with a RoutingSettings => RoutingSettingsUnaryOperator<RoutingSettings> function
mapUnmatchedPath Transforms the unmatchedPath of the RequestContextRequestContext using a Uri.Path => Uri.PathUnaryOperator<Uri.Path> function
method Rejects all requests whose HTTP method does not match the given one
onComplete “Unwraps” a Future[T]CompletionStage<T> and runs the inner route after future completion with the future’s value as an extraction of type Try[T]Try<T>
onCompleteWithBreaker “Unwraps” a Future[T]CompletionStage<T> inside a CircuitBreakerCircuitBreaker and runs the inner route after future completion with the future’s value as an extraction of type Try[T]Try<T>
onSuccess “Unwraps” a Future[T]CompletionStage<T> and runs the inner route after future completion with the future’s value as an extraction of type T
optionalAttribute Extracts the value of an optional request attribute with a given key
optionalCookie Extracts the HttpCookiePairHttpCookiePair with the given name as an Option[HttpCookiePair]Optional<HttpCookiePair>
optionalHeaderValue Extracts an optional HTTP header value using a given HttpHeader => Option[T]Function<HttpHeader, Optional<T>> function
optionalHeaderValueByName Extracts the value of the first optional HTTP request header with a given name
optionalHeaderValueByType Extracts the first optional HTTP request header of the given type
optionalHeaderValuePF Extracts an optional HTTP header value using a given PartialFunction[HttpHeader, T]PartialFunction<HttpHeader, T>
options Rejects all non-OPTIONS requests
overrideMethodWithParameter Changes the request method to the value of the specified query parameter
parameter Extracts a query parameter value from the request
parameterMap Extracts the request’s query parameters as a Map[String, String]Map<String, String>
parameterMultiMap Extracts the request’s query parameters as a Map[String, List[String]]Map<String, List<String>>
parameters Extracts a number of query parameter values from the request
parameterSeq Extracts the request’s query parameters as a Seq[(String, String)]List<Map.Entry<String, String>>
pass Always simply passes the request on to its inner route, i.e. doesn’t do anything, neither with the request nor the response
patch Rejects all non-PATCH requests
path Applies the given PathMatcher to the remaining unmatched path after consuming a leading slash
pathEnd Only passes on the request to its inner route if the request path has been matched completely
pathEndOrSingleSlash Only passes on the request to its inner route if the request path has been matched completely or only consists of exactly one remaining slash
pathPrefix Applies the given PathMatcher to a prefix of the remaining unmatched path after consuming a leading slash
pathPrefixTest Checks whether the unmatchedPath has a prefix matched by the given PathMatcher after implicitly consuming a leading slash
pathSingleSlash Only passes on the request to its inner route if the request path consists of exactly one remaining slash
pathSuffix Applies the given PathMatcher to a suffix of the remaining unmatched path (Caution: check scaladocjava!)
pathSuffixTest Checks whether the unmatched path has a suffix matched by the given PathMatcher (Caution: check scaladocjava!)
post Rejects all non-POST requests
provide Injects a given value into a directive
put Rejects all non-PUT requests
rawPathPrefix Applies the given matcher directly to a prefix of the unmatched path of the RequestContextRequestContext, without implicitly consuming a leading slash
rawPathPrefixTest Checks whether the unmatchedPath has a prefix matched by the given PathMatcher
recoverRejections Transforms rejections from the inner route with an immutable.Seq[Rejection] => RouteResultFunction<List<Rejection>, RouteResult> function
recoverRejectionsWith Transforms rejections from the inner route with an immutable.Seq[Rejection] => Future[RouteResult]Function<List<Rejection], CompletionStage<RouteResult>> function
redirect Completes the request with redirection response of the given type to the given URI
redirectToNoTrailingSlashIfPresent If the request path ends with a slash, redirects to the same URI without trailing slash in the path
redirectToTrailingSlashIfMissing If the request path doesn’t end with a slash, redirects to the same URI with trailing slash in the path
reject Rejects the request with the given rejections
rejectEmptyResponse Converts responses with an empty entity into (empty) rejections
requestEncodedWith Rejects the request with an UnsupportedRequestEncodingRejectionUnsupportedRequestEncodingRejection if its encoding doesn’t match the given one
requestEntityEmpty Rejects if the request entity is non-empty
requestEntityPresent Rejects with a RequestEntityExpectedRejectionRequestEntityExpectedRejection if the request entity is empty
respondWithDefaultHeader Adds a given response header if the response doesn’t already contain a header with the same name
respondWithDefaultHeaders Adds the subset of the given headers to the response which doesn’t already have a header with the respective name present in the response
respondWithHeader Unconditionally adds a given header to the outgoing response
respondWithHeaders Unconditionally adds the given headers to the outgoing response
responseEncodingAccepted Rejects the request with an UnacceptedResponseEncodingRejectionUnacceptedResponseEncodingRejection if the given response encoding is not accepted by the client
scheme Rejects all requests whose URI scheme doesn’t match the given one
selectPreferredLanguage Inspects the request’s Accept-Language header and determines, which of a given set of language alternatives is preferred by the client
setCookie Adds a Set-Cookie response header with the given cookies
storeUploadedFile Streams one uploaded file from a multipart request to a file on disk
storeUploadedFiles Streams all uploaded files from a multipart request to files on disk
textract Extracts a number of values using a RequestContext => Tuple function
tprovide Injects a given tuple of values into a directive
validate Checks a given condition before running its inner route
withoutRequestTimeout Disables request timeouts for a given route.
withoutSizeLimit Skips request entity size check
withExecutionContext Runs its inner route with the given alternative ExecutionContext
withLog Runs its inner route with the given alternative LoggingAdapterLoggingAdapter
withMaterializer Runs its inner route with the given alternative MaterializerMaterializer
withPrecompressedMediaTypeSupport Adds a Content-Encoding: gzip response header if the entity’s media-type is precompressed with gzip header
withRangeSupport Adds Accept-Ranges: bytes to responses to GET requests, produces partial responses if the initial request contained a valid Range header
withRequestTimeout Configures the request timeouts for a given route.
withRequestTimeoutResponse Prepares the HttpResponseHttpResponse that is emitted if a request timeout is triggered. RequestContext => RequestContext function
withSettings Runs its inner route with the given alternative RoutingSettingsRoutingSettings
withSizeLimit Applies request entity size check
Found an error in this documentation? The source code for this page can be found here. Please feel free to edit and contribute a pull request.