Unmarshalling

Basic Design

Unmarshalling of instances of type A into instances of type B is performed by an Unmarshaller[A, B]. Akka HTTP also predefines a number of helpful aliases for the types of unmarshallers that you'll likely work with most:

At its core an Unmarshaller[A, B] is very similar to a function A => Future[B] and as such quite a bit simpler than its marshalling counterpart. The process of unmarshalling does not have to support content negotiation which saves two additional layers of indirection that are required on the marshalling side.

Predefined Unmarshallers

Akka HTTP already predefines a number of marshallers for the most common types. Specifically these are:

• PredefinedFromStringUnmarshallers
  • Byte
  • Short
  • Int
  • Long
  • Float
  • Double
  • Boolean
• PredefinedFromEntityUnmarshallers
  • Array[Byte]
  • ByteString
  • Array[Char]
  • String
  • akka.http.scaladsl.model.FormData
• GenericUnmarshallers
  • Unmarshaller[T, T] (identity unmarshaller)
  • Unmarshaller[Option[A], B], if an Unmarshaller[A, B] is available
  • Unmarshaller[A, Option[B]], if an Unmarshaller[A, B] is available

Implicit Resolution

The unmarshalling infrastructure of Akka HTTP relies on a type-class based approach, which means that Unmarshaller instances from a certain type A to a certain type B have to be available implicitly.

The implicits for most of the predefined unmarshallers in Akka HTTP are provided through the companion object of the Unmarshaller trait. This means that they are always available and never need to be explicitly imported. Additionally, you can simply "override" them by bringing your own custom version into local scope.

Custom Unmarshallers

Akka HTTP gives you a few convenience tools for constructing unmarshallers for your own types. Usually you won't have to "manually" implement the Unmarshaller trait directly. Rather, it should be possible to use one of the convenience construction helpers defined on the Unmarshaller companion:

Deriving Unmarshallers

Sometimes you can save yourself some work by reusing existing unmarshallers for your custom ones. The idea is to "wrap" an existing unmarshaller with some logic to "re-target" it to your type.

Usually what you want to do is to transform the output of some existing unmarshaller and convert it to your type. For this type of unmarshaller transformation Akka HTTP defines these methods:

• baseUnmarshaller.transform
• baseUnmarshaller.map
• baseUnmarshaller.mapWithInput
• baseUnmarshaller.flatMap
• baseUnmarshaller.flatMapWithInput
• baseUnmarshaller.recover
• baseUnmarshaller.withDefaultValue
• baseUnmarshaller.mapWithCharset (only available for FromEntityUnmarshallers)
• baseUnmarshaller.forContentTypes (only available for FromEntityUnmarshallers)

The method signatures should make their semantics relatively clear.

Using Unmarshallers

In many places throughput Akka HTTP unmarshallers are used implicitly, e.g. when you want to access the entity of a request using the Routing DSL.

However, you can also use the unmarshalling infrastructure directly if you wish, which can be useful for example in tests. The best entry point for this is the akka.http.scaladsl.unmarshalling.Unmarshal object, which you can use like this:

import akka.http.scaladsl.unmarshalling.Unmarshal
import system.dispatcher // ExecutionContext
implicit val materializer: Materializer = ActorMaterializer()

import scala.concurrent.Await
import scala.concurrent.duration._

val intFuture = Unmarshal("42").to[Int]
val int = Await.result(intFuture, 1.second) // don't block in non-test code!
int shouldEqual 42

val boolFuture = Unmarshal("off").to[Boolean]
val bool = Await.result(boolFuture, 1.second) // don't block in non-test code!
bool shouldBe false