Explore the Ordering API sample
samples/EventLoom.Ordering.Api
is a compact, production-shaped ASP.NET Core application. It demonstrates:
- explicit registration of immutable, versioned order events;
- an
Orderaggregate rebuilt from persisted history; - configured aggregate repository identity and short
LoadAsync/SaveAsyncoperations; - an explicit order snapshot captured every two events;
- scoped, required tenancy;
- request correlation metadata and caller-provided idempotency keys;
- a transactional outbox publisher and tenant-scoped delivery inspection;
- two provider-specific projection implementations that share the same API
surface for callers:
- PostgreSQL uses
IEfProjectionHandler<TEvent>plusConfigureProjectionModel(...); - MongoDB uses
IMongoProjectionHandler<TEvent>plus a MongoDB collection reader;
- PostgreSQL uses
- provider selection through
EventLoom:Provider = PostgreSql | MongoDb.
Run with Aspire
Section titled “Run with Aspire”PostgreSQL is the default:
dotnet run --project samples/EventLoom.Ordering.AppHostSwitch the sample to MongoDB:
dotnet run --project samples/EventLoom.Ordering.AppHost -- --EventLoom:Provider MongoDbThe AppHost reads EventLoom:Provider, starts the matching backing service, and
passes the provider name into the API:
PostgreSqlstarts PostgreSQL;MongoDbstarts MongoDB as a single-node replica set because EventLoom requires MongoDB transactions.
The sample initializes a new store only in Development through
InitializeEventLoomDevelopmentDatabaseAsync().
Provider-specific composition
Section titled “Provider-specific composition”The sample keeps provider-specific registration in separate files:
Infrastructure/OrderingPostgreSqlExtensions.csInfrastructure/OrderingMongoDbExtensions.cs
That avoids the ambiguous Transactional<,>() extension methods that appear if
one file imports both EventLoom.EntityFrameworkCore and EventLoom.MongoDb.
Both implementations register the same durable projection name,
ordering.order-summary.
Explore the API
Section titled “Explore the API”In Development, the API resource generates an OpenAPI document with
Microsoft.AspNetCore.OpenApi and exposes the Scalar interactive reference at
/scalar/v1. The generated document is at /openapi/v1.json. Use the API URL
from the Aspire dashboard rather than assuming a fixed local port.
The dashboard shows API logs plus ASP.NET Core and EventLoom traces and metrics.
The API also exposes /health for readiness and /alive for liveness. All
sample business endpoints require X-Tenant-ID.
Exercise the API
Section titled “Exercise the API”Create an order. Supplying orderId and Idempotency-Key lets a client repeat
the same command after an ambiguous response:
api_url=http://localhost:5080 # Copy the URL from the Aspire dashboard.order_id=$(uuidgen | tr '[:upper:]' '[:lower:]')
curl -X POST "${api_url}/orders" \ -H 'content-type: application/json' \ -H 'X-Tenant-ID: acme' \ -H 'X-Correlation-ID: checkout-42' \ -H 'Idempotency-Key: place-order-42' \ -d "{\"orderId\":\"${order_id}\",\"sku\":\"coffee\",\"quantity\":2}"Add an item:
curl -X POST "${api_url}/orders/${order_id}/items" \ -H 'content-type: application/json' \ -H 'X-Tenant-ID: acme' \ -d '{"sku":"filter","quantity":1}'Read the rehydrated aggregate:
curl -H 'X-Tenant-ID: acme' \ "${api_url}/orders/${order_id}"Inspect persisted envelope metadata, including stream version and tenant offset:
curl -H 'X-Tenant-ID: acme' \ "${api_url}/orders/${order_id}/events"The asynchronous order summary is intentionally eventually consistent. Poll it after sending commands:
curl -H 'X-Tenant-ID: acme' \ "${api_url}/orders/${order_id}/summary"The read path stays the same regardless of provider. Behind that endpoint:
- PostgreSQL reads an EF-mapped
OrderSummaryrow; - MongoDB reads an
ordering_order_summariesdocument throughMongoSessionAccessor.Database.
Inspect the summary projection’s tenant checkpoint and any persisted failures:
curl -H 'X-Tenant-ID: acme' \ "${api_url}/projections/order-summary"The sample also exposes explicit tenant-scoped recovery routes:
POST /projections/order-summary/resumePOST /projections/order-summary/replayPOST /projections/order-summary/failures/{eventId}/skipEach event is also written to the outbox. This sample retains successful
delivery records for one day. Replace <event-id> with the event’s eventId
from the event-history response to inspect the delivery record and attempts:
curl -H 'X-Tenant-ID: acme' \ "${api_url}/outbox/<event-id>"Run the same sequence under both providers to compare behavior. Command and query endpoints stay stable; only the provider wiring and transactional projection implementation change.