.. _routing-java: Routing DSL Overview ==================== The Akka HTTP :ref:`http-low-level-server-side-api-java` provides a ``Flow``- or ``Function``-level interface that allows an application to respond to incoming HTTP requests by simply mapping requests to responses (excerpt from :ref:`Low-level server side example `): .. includecode:: ../../code/docs/http/javadsl/HttpServerExampleDocTest.java :include: request-handler While it'd be perfectly possible to define a complete REST API service purely by inspecting the incoming ``HttpRequest`` this approach becomes somewhat unwieldy for larger services due to the amount of syntax "ceremony" required. Also, it doesn't help in keeping your service definition as DRY_ as you might like. As an alternative Akka HTTP provides a flexible DSL for expressing your service behavior as a structure of composable elements (called :ref:`directives-java`) in a concise and readable way. Directives are assembled into a so called *route structure* which, at its top-level, can be used to create a handler ``Flow`` (or, alternatively, an async handler function) that can be directly supplied to a ``bind`` call. Here's the complete example rewritten using the composable high-level API: .. includecode:: ../../code/docs/http/javadsl/HighLevelServerExample.java :include: high-level-server-example Heart of the high-level architecture is the route tree. It is a big expression of type ``Route`` that is evaluated only once during startup time of your service. It completely describes how your service should react to any request. The type ``Route`` is the basic building block of the route tree. It defines if and a how a request should be handled. Routes are composed to form the route tree in the following two ways. A route can be wrapped by a "Directive" which adds some behavioral aspect to its wrapped "inner route". ``path("ping")`` is such a directive that implements a path filter, i.e. it only passes control to its inner route when the unmatched path matches ``"ping"``. Directives can be more versatile than this: A directive can also transform the request before passing it into its inner route or transform a response that comes out of its inner route. It's a general and powerful abstraction that allows to package any kind of HTTP processing into well-defined blocks that can be freely combined. akka-http defines a library of predefined directives and routes for all the various aspects of dealing with HTTP requests and responses. Read more about :ref:`directives-java`. The other way of composition is defining a list of ``Route`` alternatives. Alternative routes are tried one after the other until one route "accepts" the request and provides a response. Otherwise, a route can also "reject" a request, in which case further alternatives are explored. Alternatives are specified by passing a list of routes either to ``Directive.route()`` as in ``pathSingleSlash().route()`` or to directives that directly take a variable number of inner routes as argument like ``get()`` here. Read more about :ref:`routes-java`. Another important building block is a ``RequestVal``. It represents a value that can be extracted from a request (like the URI parameter ``Parameters.stringValue("name")`` in the example) and which is then interpreted as a value of type ``T``. Examples of HTTP aspects represented by a ``RequestVal`` are URI parameters, HTTP form fields, details of the request like headers, URI, the entity, or authentication data. Read more about :ref:`request-vals-java`. The actual application-defined processing of a request is defined with a ``Handler`` instance or by specifying a handling method with reflection. A handler can receive the value of any request values and is converted into a ``Route`` by using one of the ``BasicDirectives.handleWith`` directives. Read more about :ref:`handlers-java`. Requests or responses often contain data that needs to be interpreted or rendered in some way. Akka-http provides the abstraction of ``Marshaller`` and ``Unmarshaller`` that define how domain model objects map to HTTP entities. Read more about :ref:`marshalling-java`. akka-http contains a testkit that simplifies testing routes. It allows to run test-requests against (sub-)routes quickly without running them over the network and helps with writing assertions on HTTP response properties. Read more about :ref:`http-testkit-java`. .. _DRY: http://en.wikipedia.org/wiki/Don%27t_repeat_yourself