Typesafe Activator

Akka persistence event sourcing

Akka persistence event sourcing

August 23, 2014
akka persistence akka-persistence event-sourcing spray scaladays2014 scala

Example project with a simple CRUD REST API to a domain model persisted using akka-persistence with event sourcing.

How to get "Akka persistence event sourcing" on your computer

There are several ways to get this template.

Option 1: Choose akka-persistence-event-sourcing in the Typesafe Activator UI.

Already have Typesafe Activator (get it here)? Launch the UI then search for akka-persistence-event-sourcing in the list of templates.

Option 2: Download the akka-persistence-event-sourcing project as a zip archive

If you haven't installed Activator, you can get the code by downloading the template bundle for akka-persistence-event-sourcing.

  1. Download the Template Bundle for "Akka persistence event sourcing"
  2. Extract the downloaded zip file to your system
  3. The bundle includes a small bootstrap script that can start Activator. To start Typesafe 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\akka-persistence-event-sourcing> activator ui 
    This will start Typesafe Activator and open this template in your browser.

Option 3: Create a akka-persistence-event-sourcing project from the command line

If you have Typesafe Activator, use its command line mode to create a new project from this template. Type activator new PROJECTNAME akka-persistence-event-sourcing on the command line.

Option 4: View the template source

The creator of this template maintains it at https://github.com/ScalaConsultants/akka-persistence-eventsourcing#master.

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


Example project with a simple CRUD REST API to a domain model persisted using akka-persistence with event sourcing.

Project summary:

  • simple CRUD REST API
  • Spray "actor per request" model inspired by spray-actor-per-request Activator template and Cameo Pattern from Jamie Allen's "Effective Akka"
  • simple domain model representing a Vehicle and User
  • akka-persistence event sourcing used to track changes to the domain model

Explore the app

Once the application is started you can test it's functionality by invoking http requests. You can do it using any tool you like (some useful ones are Postman for Chrome or RESTClient for Firefox).

All accessible routes are defined in VehicleRoute.scala and UserRoute.scala files.
Example requests for each route are shown below (POST ones require header "Content-Type: application/json" to be set):

Registering user

                POST http://localhost:8080/api/user
                {"name": "John", "pass": "s3cr3t"}

Changing user's password (requires user authentication)

                POST http://localhost:8080/api/user/password
                {"pass": "newPassword"}

Creating vehicle (requires user authentication)

                POST http://localhost:8080/api/vehicles
                {"regNumber": "123", "color": "red"}

Retrieving vehicle

                GET http://localhost:8080/api/vehicles/{vehicle-id}

Deleting vehicle (requires user authentication)

                DELETE http://localhost:8080/api/vehicles/{vehicle-id}

Changing vehicle's regNumber (requires user authentication)

                POST http://localhost:8080/api/vehicles/{vehicle-id}/regNumber
                {"value": "newRegNumber"}

Changing vehicle's color (requires user authentication)

                POST http://localhost:8080/api/vehicles/{vehicle-id}/color
                {"value": "newColor"}

Request handlers

Every time new request is received an instance of specific RequestHandler actor is created.

Since each request can result in different status code for the same aggregate state (for example Removed state for GET request should result in NotFound, for DELETE however it should return NoContent) there are separate actors for each possible request (RegisterRequestActor, DeleteRequestActor, etc.).

When such RequestHandler actor is created it immediately sends a message to AggregateManager actor, which handles the request and returns the result. RequestHandler actor handles result returned from AggregateManager and responds with proper http response.

This pattern is inspired by spray-actor-per-request Activator template and more information can be found there.

Event sourcing

When AggregateManager receives new command it instantiates new aggregate actor and forwards command to it.

When aggregate is instantiated it is restored from historical events (akka persistence module takes care of it).

Only when aggregate is fully restored it can handle "regular" messages (commands in this case).

When aggregate receives new command it creates an event out of it and persists it in journal. Persisted event is then applied to aggregate.

For more information, please refer to Akka persistence documentation.


Snapshots are used to reduce recovery time of aggregates.

VehicleAggregate handles taking snapshots itself. It tracks number of processed events and takes snapshot once 10 of them were processed.

Learning resources

Here you'll find some learning resources that we strongly recommend in order to fully understand how does the application work.

comments powered by Disqus