ReST vs CQRS: The Trigger Pattern

Matt Hawkins @mattchawkins

Introduction

I've found that most online examples/blogs of Command Query Responsibility Segregation (CQRS) with Event Sourcing (ES) and Domain Driven Design (DDD) are fairly trivial. After trudging the road to create one of these behemoths on a production scale, in a complex financial domain, I’ve discovered that CQRS and ReST can be quite orthogonal.

The problem arises when you consider the limited number of HTTP methods that you have to execute non-query requests on the ReSTful API. In this blog post we’re going to focus on two verbs: POST and PUT. How do you perform multiple complex state changes with one or two verbs while still being ReSTful and not providing explicit intent to the API? I’ve found a few compelling solutions to this problem, with the winner being the trigger pattern.

Part 1: Domain Model

Let’s consider the domain of a Car. We’ll assume this domain requires a granular log of all state changes. Obviously we wouldn’t be changing CarID, but it’s likely the Color, Mileage, Condition, and Owner may change during a car’s lifecycle.

 1: 
 2: 
 3: 
 4: 
 5: 
 6: 
 7: 
 8: 
 9: 
10: 
11: 
12: 
13: 
14: 
15: 
16: 
17: 
18: 
19: 
20: 
21: 
22: 
23: 
24: 
25: 
26: 
27: 
28: 

[<CustomEquality;NoComparison>]
type Car =
  { CarID     : Guid 
    Year      : int
    CarType   : CarType
    Color     : Color
    Mileage   : int
    VIN       : string
    Condition : Condition
    Owner     : Guid }
  // DDD Entities have identity equality
  override this.Equals (that :obj) =
    match that with                                     
    | :? Car as that  -> this.CarID = that.CarID  
    | _               -> false  
  override this.GetHashCode () =
    hash this
and CarType =
  | Ford of Ford
  | BMW  of BMW
and Ford =
  | Escape | F150  
and BMW =
  | M3 | M5 
and Color =
  | Red | White | Blue
and Condition =
  | Excellent | Good | Average | Poor

Above is the Domain Model of a Car. All of these associated domain types represent an Aggregate in Domain Driven Design.

 1: 
 2: 
 3: 
 4: 
 5: 
 6: 
 7: 
 8: 
 9: 
10: 
11: 
12: 
13: 

type CarEvents =
  | Created          of  carID     :Guid 
                       * year      :int
                       * CarType   
                       * Color     
                       * mileage   :int
                       * vin       :string
                       * owner     :Guid
                       * condition :Condition
  | ColorChanged     of Color      
  | MileageChanged   of mileage    :int
  | ConditionChanged of Condition  
  | OwnerChanged     of owner      :Guid

Events model all possible state changes in a granular delta representation; the event only contains what has changed. There are a few different approaches to modeling events (granular delta's, snapshots, and before-and-after’s); depending on the requirement, you can choose accordingly.

Part 2: The ReSTful API

Providing an API to your domain model is how you affect change on it. Below we have two API endpoints, a POST and a PUT. For this example, POST will be used to create an instance of Car and PUT will be used to update an instance of Car. CQRS API's are typically light weight and have two job's, to fire-and-forget commands and to provide a data via query (GET).

1: 
2: 
3: 
4: 
5: 
6: 
7: 
8: 

// POST: {address}/cars
let postEndpoint httpRequest =
  let carID = Guid.NewGuid()
  { httpRequest.Body with CarID = carID}
  |> Create 
  |> sendToQueue
  // Return a 200 with the CarID
  OK (carID)

The POST endpoint parses the JSON body of the request:

1: 2: 3: 4: 5: 6: 7: 8: 9: 10:

{ "year": 2009, "make": "BMW", "model": "M3", "color": "black", "mileage": 14320, "vin": "2G4GM5ER4E9225618", "condition": "good", "owner": "ad4181f8-c33f-4e81-9d9e-0896188d73f0" }

Then pipes the deserialized Car representation into an instance of a Create command and places it on the command queue.

1: 
2: 
3: 
4: 
5: 
6: 
7: 

// PUT: {address}/cars/{carID}
let putEndpoint uri httpRequest =
  let carID = extractID uri
  { httpRequest.Body with CarID = carID }
  |> Update
  |> sendToQueue
  Accepted ()

The PUT endpoint is very similar to the POST endpoint except it includes the identifier of the Car in the URI as shown above. We simply use the F# with keyword to effectivly update the Car representation with the CarID, pipe it into an instance of Update command, and place the command on the command queue.

Part 3: The Command & Trigger Patterns

As shown above, the API publishes commands onto the command queue, which is then consumed by a command handler. Let's take a closer look at the commands:

 1: 
 2: 
 3: 
 4: 
 5: 
 6: 
 7: 
 8: 
 9: 
10: 
11: 
12: 
13: 
14: 

type CarCommands =
  | Create of CarRepresentation
  | Update of CarRepresentation
  | Delete of carID:Guid
and CarRepresentation = 
  { CarID     : Guid
    Year      : int
    Make      : string
    Model     : string
    Color     : string
    Mileage   : int
    VIN       : string
    Condition : string
    Owner     : Guid }

Notice the only responsiblity of the command is to encapsulate the Car's API representation, CarRepresentation.

Now let's examine how the command is handled. The commandHandler is responsible for consuming the command, validating it, and working with the Aggregate Root. The root may return an event which is then persisted and broadcasted.

1: 
2: 
3: 
4: 
5: 
6: 

let commandHandler command = choice {
  let! currentState,triggers = TriggerBuilder.map command
  let! finalState  ,events   = triggers |> execute root currentState
  do! events |> EventStore.saveEvents finalState.CarID
  do! broadcast events
  return ()}

The TriggerBuilder.map function takes an API command, data-type validates it, and maps it into domain trigger(s). Data-type validation is simply confirming that Guid's are not empty and strings map to their proper enum's, etc.

 1: 
 2: 
 3: 
 4: 
 5: 
 6: 
 7: 
 8: 
 9: 
10: 
11: 
12: 
13: 

type CarTriggers =
  | Create          of  carID     :Guid
                      * year      :int
                      * CarType   
                      * Color     
                      * mileage   :int
                      * vin       :string
                      * owner     :Guid
                      * condition :Condition
  | ChangeColor     of Color      
  | UpdateMileage   of mileage    :int
  | UpdateCondition of Condition  
  | ChangeOwner     of owner      :Guid

CarTriggers Trigger domain type provides explicit actions you can take against the Aggregate. CarCommands from the API have implicit intent, as you're just PUT'ing the future state of the Car to the API, whereas CarTriggers have explicit intent, and provide a precise modeling mechanism for complex state changes.

1: 
2: 
3: 
4: 
5: 
6: 
7: 
8: 
9: 

module TriggerBuilder =
  // ...
  // Code commented out for readability, see examples below
  // ...
  let map command = 
    match command with
    | CarCommands.Create car   -> mapCreate car
    | CarCommands.Update car   -> mapUpdate car
    | CarCommands.Delete carID -> mapDelete carID

The TriggerBuilder matches on the CarCommands type and provides the CarRepresentation from the command to the mapping function (mapCreate, mapUpdate, or mapDelete).

The responsibility of the trigger mapping functions (mapCreate, mapUpdate, or mapDelete), are to 1) data-type validate the representation 2) determine which domain triggers to return. The data-type validation is quite trivial:

 1: 
 2: 
 3: 
 4: 
 5: 
 6: 
 7: 
 8: 
 9: 
10: 

let validateRepresentation (payload:CarRepresentation) = choice {
  // Simple type validation & mapping -> No domain validation here!
  let! carID     = validateID payload.CarID
  let! carType   = mapCarType payload
  let! color     = mapEnum<Color> payload.Color
  let! vin       = isValidString payload.VIN
  let! condition = mapEnum<Condition> payload.Condition
  let! ownerID   = validateID payload.Owner
  // Return all the mapped & validated types
  return carID,payload.Year,carType,color,payload.Mileage,vin,ownerID,condition }

Simple type validation and mapping of primitives to value types. ("Value Types" in the context of Domain Driven Design)

1: 
2: 
3: 
4: 

// Validate & map representation into domain types, and create the trigger
let mapCreate = validateRepresentation 
                >> Choice.map (Create >> List.singleton) 
                >> Choice.map (fun e -> root.Zero (),e)

mapCreate validates & maps the API representation CarRepresentation, then makes a Create trigger, finally mapping into a Tuple with the zero state of the Aggregate Root (see Part 4). The trigger builder will return this ('State * 'Triggers list) tuple back to the Command Handler, where it is then fired against the Aggregate Root; thus producing domain events.

Finally the part you've been waiting for. How does the system magically figure out what state been changed from the PUT API representation? Truth is, it's not that magical.

1: 
2: 
3: 
4: 

let mapUpdate representation = choice {
  let! carID,_,_,color,mileage,_,owner,condition = validateRepresentation representation
  let! currentState = EventStore.rehydrate<Car> carID
  return! compare currentState (color,mileage,owner,condition) }

mapUpdate data-type validates the CarRepresentation the same way the mapCreate function does. The compare function is where the analysis happens.

 1: 
 2: 
 3: 
 4: 
 5: 
 6: 
 7: 
 8: 
 9: 
10: 
11: 
12: 
13: 
14: 
15: 
16: 

let compare current proposed = choice {
  // Figure out what has changed!
  let proposedColor,proposedMileage,proposedOwner,proposedCondition = proposed
  let changeColorTrigger     = proposedColor     |> evalColor     current.Color
  let updateMileageTrigger   = proposedMileage   |> evalMileage   current.Mileage
  let changeOwnerTrigger     = proposedOwner     |> evalOwner     current.Owner
  let updateConditionTrigger = proposedCondition |> evalCondition current.Condition
  // Controls the order in which the triggers fire to the aggregate
  return
    current,
    [changeColorTrigger
     updateMileageTrigger
     changeOwnerTrigger
     updateConditionTrigger]
    |> List.choose some }
     

Each eval function evaluates the current and proposed state, returning a Trigger option.

1: 
2: 
3: 
4: 

let evalColor current proposed =
  if current = proposed
    then None
    else Some <| ChangeColor proposed

evalColor evaluates current and proposed color, returning a ChangeColor option (Trigger).

To summarize the Command Handler, it consists of the following components:
1. Trigger Builder
-Maps "implicit intent" API Commands to "explicit intent" Domain Triggers.
2. Execution
-Involves rehydration of the Aggregate from the event store and firing of the Triggers against the Aggregate Root, which result in Domain Events.
3. Persistence & Broadcasting
-Saving the Domain Events to durable storage (Event Store) and broadcasting said events to interested parties.

Part 4: CQRS Aggregate Root

The Domain Driven Design Aggregate Root is the "chosen" entity that is responsible for consistency within the aggregates type's and acts as a liason to the outside world. In this example the Aggregate Root was a Car. Consider the abstract notion of the DDD Aggregate Root with the following concrete type definition of a CQRS Aggregate Root:

1: 
2: 
3: 
4: 

type AggregateRoot<'state,'event,'trigger> =
  { Zero  :  unit  -> 'state
    Apply : 'state -> 'event   -> 'state
    Fire  : 'state -> 'trigger ->  Choice<'event,DomainError> }

AggregateRoot type implemented for the Car aggregate root:

1: 
2: 
3: 
4: 

let root = 
  { Zero  = (fun _ -> Unchecked.defaultof<Car>)
    Apply =  applyFn
    Fire  =  fireFn }

 1: 
 2: 
 3: 
 4: 
 5: 
 6: 
 7: 
 8: 
 9: 
10: 
11: 
12: 
13: 
14: 
15: 
16: 
17: 
18: 
19: 
20: 
21: 

let fireFn = 
  (fun state trigger -> 
    match trigger with
    | Create (carID,year,carType,color,mileage,vin,owner,condition) -> choice {
        // Domain validation
        let! carID   = validateID carID
        let! year    = carType |> validateYear year
        let! mileage = isNonNegative mileage
        // Return the domain event
        return Created (carID,year,carType,color,mileage,vin,owner,condition) }
    | ChangeColor (color) -> 
        // No validation necessary
        ColorChanged color |> Choice.result
    | UpdateMileage (mileage) -> choice {
        // Domain validation
        let! mileage = mileage |> isGreaterThan state.Mileage
        return MileageChanged mileage }
    | UpdateCondition (condition) ->
        ConditionChanged condition |> Choice.result
    | ChangeOwner (ownerID) ->
        OwnerChanged ownerID |> Choice.result)

 1: 
 2: 
 3: 
 4: 
 5: 
 6: 
 7: 
 8: 
 9: 
10: 
11: 
12: 
13: 
14: 
15: 
16: 
17: 
18: 
19: 
20: 

let applyFn =
  (fun state event ->
    match event with 
    | Created (carID,year,carType,color,mileage,vin,owner,condition) ->
        { state with CarID     = carID
                     Year      = year
                     CarType   = carType
                     Color     = color
                     Mileage   = mileage
                     VIN       = vin
                     Owner     = owner
                     Condition = condition }
    | ColorChanged (color) ->
        { state with Color = color }
    | MileageChanged (mileage) ->
        { state with Mileage = mileage }
    | ConditionChanged (condition) ->
        { state with Condition = condition }
    | OwnerChanged (ownerID) ->
        { state with Owner = ownerID })

Notice the AggregateRoot type has 3 functions. Zero provides a starting state for the Aggregate Root, frequently used during rehydration/hydration of Domain Events. Apply provides model rehydration functionality. Fire is a function that takes the current state of the Aggregate and a Domain Trigger, and returns a Domain Event.

Closing Thoughts

There are many ways to expose domain actions through an API. The Trigger Pattern approach is one that strives to allow you to maintain somewhat of a ReSTful API. Another approach I've encountered (but haven't tested), is moving the "trigger" logic into the client, effectively placing a command-type in the request headers. I feel this approach is may be moving you torwards RPC rather than ReST, but it is another option. A similar alternative is just using the PATCH verb, where the client supplies the delta change to the API, effectively eliminating the need for Triggers in the most trivial of cases.

Written by:
Matt Hawkins |
December 18th 2015 |
Twitter: @mattchawkins |