Lightbend Activator

Actor per-request model with spray

Actor per-request model with spray

March 13, 2015
akka spray rest scala

Example spray RESTful API using the actor per request model

How to get "Actor per-request model with spray" on your computer

There are several ways to get this template.

Option 1: Choose spray-actor-per-request in the Lightbend Activator UI.

Already have Lightbend Activator (get it here)? Launch the UI then search for spray-actor-per-request in the list of templates.

Option 2: Download the spray-actor-per-request project as a zip archive

If you haven't installed Activator, you can get the code by downloading the template bundle for spray-actor-per-request.

  1. Download the Template Bundle for "Actor per-request model with spray"
  2. Extract the downloaded zip file to your system
  3. The bundle includes a small bootstrap script that can start Activator. To start Lightbend Activator's UI:

    In your File Explorer, navigate into the directory that the template was extracted to, right-click on the file named "activator.bat", then select "Open", and if prompted with a warning, click to continue:

    Or from a command line:

     C:\Users\typesafe\spray-actor-per-request> activator ui 
    This will start Lightbend Activator and open this template in your browser.

Option 3: Create a spray-actor-per-request project from the command line

If you have Lightbend Activator, use its command line mode to create a new project from this template. Type activator new PROJECTNAME spray-actor-per-request on the command line.

Option 4: View the template source

The creator of this template maintains it at

Option 5: Preview the tutorial below

We've included the text of this template's tutorial below, but it may work better if you view it inside Activator on your computer. Activator tutorials are often designed to be interactive.

Preview the tutorial

Spray Actor Per Request


This project provides an example spray application that uses the Actor per request model.

Why would you want to spin up an Actor for each HTTP request?

  • Easily manage any request scoped Actors in the application core
    • The per request actor can clean them up in the event of a timeouts and failures
  • Promote Tell, Don't Ask
    • Using request scoped Actors in the application core can make it easier to use tell (!) over ask (?)


  • Scala Exchange Presentation (video)
  • Mathias describes the actor per request approach against others. (mailing list)

App Overview

This example application provides an API to get a list of pets with their owners. There are already two services that provide a list of pets and a list of animals and the responsibility of this application is to simply aggregate these two together.

Our application is made up of three modules:

  • Application Core - The core module contains the business logic for our application. In this example this is how we aggregate pets with their owners.
  • Routing - The routing module contains our spray routing which describes our RESTful endpoints. It also contains our PerRequest actor which bridges the gap between the routing and the `core` modules and contains the piece of code this example project aims to demonstrate.
  • Clients - Our code to consume two existing services that provide us with a list of pets and a list of owners. These services could be databases, RESTful APIs, etc. It doesn't really matter for the purposes of this example.

Ideally modules these would be in separate sub-projects to prevent compile time dependencies, however for simplicity purposes they are just kept in separate packages in this example.

Successful request

If we request the pet Lassie:

GET http://localhost:38080/pets?names=Lassie

We get a successful response:

  "pets": [
      "name": "Lassie",
      "owner": {
        "name": "Jeff Morrow"

In this scenario, any request scoped actors in the application core are stopped by the PerRequest actor.

Request Timeouts

Tortoises are slow. If we request a tortoise the PetClient will not reply to our application core quick enough. The timeout of 2 seconds in our PerRequest actor will happen first.

GET http://localhost:38080/pets?names=Tortoise
  "message": "Request timeout"

In this scenario, any request scoped actors in the application core are stopped by the PerRequest actor.


You shouldn't keep a Lion as a pet. Quite frankly they are too dangerous.

GET http://localhost:38080/pets?names=Lion
  "message": "Lions are too dangerous!"

In this scenario, our application core returns a generic Validation message to our PerRequest actor to complete. Any request scoped actors in the application core are stopped by the PerRequest actor.


What about unexpected failures? There is a "bug" in our application core that throws a PetOverflowException if we request too many pets:

GET http://localhost:38080/pets?names=Lassie,Tweety,Tom
  "message": "PetOverflowException: OMG. Pets. Everywhere."

Any failures that not handled by the application core can be escalated up to the supervision strategy in our PerRequest actor. The PerRequest actor is too generic to recover from any business logic failures, so it will simply handle all failures by completing the request with an error response. Any request scoped actors in the application core are stopped by the PerRequest actor.