def handleWith[A, B](f: A => B)(implicit um: FromRequestUnmarshaller[A], m: ToResponseMarshaller[B]): Route


Completes the request using the given function. The input to the function is produced with the in-scope entity unmarshaller and the result value of the function is marshalled with the in-scope marshaller. handleWith can be a convenient method combining entity with complete.

The handleWith directive is used when you want to handle a route with a given function of type A => BFunction<A,B>. handleWith will use both an in-scope unmarshaller to convert a request into type A and an in-scope marshaller to convert type B into a response. This is helpful when your core business logic resides in some other class or you want your business logic to be independent of the REST interface written with akka-http. You can use handleWith to “hand off” processing to a given function without requiring any akka-http-specific functionality.

handleWith is similar to produce. The main difference is handleWith automatically calls complete when the function passed to handleWith returns. Using produce you must explicitly call the completion function passed from the produce function.

See marshalling and unmarshalling for guidance on marshalling entities with akka-http.


The following example uses an updatePerson function with a Person case class as an input and output. We plug this function into our route using handleWith.

sourcecase class Person(name: String, favoriteNumber: Int)
sourcestatic public class Person {
  private final String name;
  private final int favoriteNumber;

  //default constructor required for Jackson
  public Person() {
    this.name = "";
    this.favoriteNumber = 0;

  public Person(String name, int favoriteNumber) {
    this.name = name;
    this.favoriteNumber = favoriteNumber;

  public String getName() {
    return name;

  public int getFavoriteNumber() {
    return favoriteNumber;
sourceimport PersonJsonSupport._

val updatePerson = (person: Person) => {

  //... some processing logic...

  //return the person

val route = post {

// tests:
Post("/", HttpEntity(`application/json`, """{ "name": "Jane", "favoriteNumber" : 42 }""")) ~>
  route ~> check {
    mediaType shouldEqual `application/json`
    responseAs[String] should include(""""name":"Jane"""")
    responseAs[String] should include(""""favoriteNumber":42""")
sourceimport static akka.http.javadsl.server.Directives.handleWith;

final Unmarshaller<HttpEntity, Person> unmarshaller = Jackson.unmarshaller(Person.class);
final Marshaller<Person, HttpResponse> marshaller = Marshaller.entityToOKResponse(Jackson.<Person>marshaller());

final Function<Person, Person> updatePerson = person -> {

  //... some processing logic...

  //return the person
  return person;

final Route route = handleWith(unmarshaller, marshaller, updatePerson);

// tests:
final TestRouteResult routeResult = testRoute(route).run(
        ContentTypes.APPLICATION_JSON, "{\"name\":\"Jane\",\"favoriteNumber\":42}"

The PersonJsonSupport object handlesprevious example uses also Json Support via Jackson to handle both marshalling and unmarshalling of the Person case class.

sourceimport spray.json.{ DefaultJsonProtocol, RootJsonFormat }

object PersonJsonSupport extends DefaultJsonProtocol with SprayJsonSupport {
  implicit val personFormat: RootJsonFormat[Person] = jsonFormat2(Person.apply)
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.