API first REST in Akka and Spray

Another update to https://github.com/janm399/akka-patterns shows how to build and test REST application in Akka and Spray using API first approach, where we begin by defining the API and writing tests that check the API and then, independently, implement the rest of the system; finally swapping out the mock API for the real implementation and re-running the tests.

The most interesting points include the API tests (in Specs2, naturally!):

class CustomerServiceSpec extends DefaultApiSpecification {
  implicit val service = rootService

  "Getting a known customer works" in {
    val customer = perform[Customer](GET, 
                    "/customers/00000000-0000-0000-0000-000000000000")

    customer must_== janMachacek
  }

  "Finding all customers works" in {
    val customers = perform[List[Customer]](GET, "/customers")

    customers must contain (janMachacek)
  }

  "Saving a customer gets the saved one" in {
    val customer = perform[Customer](POST, "/customers", 
                     jsonContent("/org/.../customers-post.json"))

    customer must_== joeBloggs
  }

}

The DefaultApiSpecification mixes in the functionality of the Core and Api traits, together with SpecConfiguration, Specification and a few others to allow us to simply write perform[A](...): A.

Looking into the guts of the application, it is an absolute joy to be able to use typeclasses for persistence with Casbah to persist our instances in MongoDB:

case class Get(id: UUID)
case class FindAll()
case class Insert(customer: Customer)

class CustomerActor extends Actor 
  with Configured with TypedCasbah with SearchExpressions {

  def customers = configured[MongoDB].apply("customers")

  protected def receive = {
    case Get(id) =>
      sender ! customers.findOne(entityId(id)).map(mapper[Customer])

    case FindAll() =>
      sender ! customers.find().map(mapper[Customer]).toList

    case Insert(customer) =>
      customers += serialize(customer)
      sender ! customer
  }
}

Before you say anything about trivial values to persist, the Customer case class is defined as

case class Customer(firstName: String, lastName: String,
                    email: String, addresses: Seq[Address],
                    id: UUID)

case class Address(line1: String, line2: String, line3: String)

But enough dry text, here’s a video of how I put the whole thing together: