Lightbend Activator

Actor per-request model with spray

Activator will be EOL-ed on May 24, 2017.

We’re making it easier and simpler for developers to get started with Lightbend technologies. This unfortunately means that future releases of Play, Akka and Scala will no longer include Activator support, and Lightbend’s Activator server will be decommissioned by the end of 2017. Instead of supporting Activator to create and set up development projects, we'll be supporting standard Giter8 templates for sbt users and Maven archetypes for Maven users. So going forward,

To create new Lightbend projects

Instead of using the Activator command, make sure you have sbt 0.13.13 (or higher), and use the “sbt new” command, providing the name of the template. For example, “$ sbt new akka/hello-akka.g8”. You can find a list of templates here.

Also, as a convenience, the Lightbend Project Starter allows you to quickly create a variety of example projects that you just unzip and run.

To create new templates

If you want to create new templates, you can now do that in Giter8.

To migrate templates from Activator to Giter8

If you created Activator templates in the past, please consider migrating them to Giter8 with this simple process.

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.