Special Query Params

Most of our endpoints accept the following query parameters:

branchId

Used to target a specific branch, it is mandatory for all commands (except initializePolicy and createBranch).

Most read models support this parameter. If not given, the read model will return the state as defined by the main version plus any changes made on the current branch.

Please refer to branch object if needed.

whenAt

Available in:

• Commands (POST)
• Read models (GET)

Default value: now

Refer to date handling section to see how whenAt dates are handled.

whenAt in Commands (~POST)

When present as a query parameter, whenAt will force the timestamp createdAt of the event created by the command to be equal to whenAt.
It allows to "cheat" with the time, making a query in the past or in the future.

danger

Using whenAt in Commands is not possible in production. It will only be available in sandbox environments.

Let's imagine we are July 7, 2023 and you initialize a policy with a whenAt on March 20, 2023, the policy will effectively appeared as created on March 20, 2023, even though it was created on July 7, 2023

whenAt in Read Models (~GET)

When present as a query parameter, whenAt will force the endpoint to return the state of your model at that exact date in time.
It is very powerful if you want to see what an endpoint would have answered at an exact time in the past.

info

Using whenAt in Read Models will be available in both sandbox and production environments.

When given, endpoints will reflect database state at the given date, i.e. the events that were created at that date. For example:

You create a policy on March 1, 2023, defining its start date to be on March 10, 2023. You then quote it and confirm it on March 2, 2023.

You retrieve the policy object with whenAt on February 28, 2023, it does not exist yet.

You retrieve the policy object with whenAt on March 1, 2023, it exists and is CREATED.

You retrieve the policy object with whenAt on March 11, 2023, it exists and is CONFIRMED.

simulatedAt

Available in:

• Read models (GET)

Default value: now

Refer to date handling section to see how simulated dates are handled.

simulatedAt in Read Models (~GET)

When experimenting with this parameter on queries, in the read models only, you may find similar results than with the whenAt parameter, but it is more subtle.

Where whenAt restricts queries to events created at the given date, simulatedAt restricts queries to events effective at the given date.

If we slightly change our previous example:

You create a policy on March 1, 2023, defining its start date to be on March 25, 2023.

You retrieve the policy object with simulatedAt on March 24, 2023 and whenAt on February 28, 2023, it does not exist yet.

You retrieve the policy object with simulatedAt on March 24, 2023 and whenAt on March 1, 2023, it exists and is CREATED.

You retrieve the policy object with simulatedAt on March 25, 2023 and whenAt on February 28, 2023, it does not exist yet.

You retrieve the policy object with simulatedAt on March 25, 2023 and whenAt on March 1, 2023, it exists and is STARTED.

What happened ?

The policy object was created on March 1, 2023 and the event indicating its start will be created on March 25, 2023.

As such, retrieving policy state with the whenAt parameter will take into account events that are created at the requested date. In this case, the start event does not exist on March 1, 2023 and so the policy is CREATED.
However, retrieving policy state with the simulatedAt parameter will take into account events according to when they should be applied. In this case, the start event is applied on March 25, 2023 and so the policy is STARTED.