✅ RFC 7515 - JSON Web Signature (JWS) for response signing, via X-JWS-Signature header

✅ RFC 7517 - JSON Web Key Set (JWKs) for validating JWS responses, via /.well-known/jwks.json endpoint

EDA (Event-driven architecture) with outbox-pattern

✅ OpenAPI Specification v3.1.1 - webhook field

✅ CloudEvents - Version 1.0.2 for defining the format of event data

✅ CloudEvents - Version 1.0.2 - HTTP Protocol Binding for HTTP transport

✅ CloudEvents - Version 1.0.2 - HTTP 1.1 Web Hooks for Event Delivery for delivering events via the webhook pattern

MCP Server

✅ Model Context Protocol, version 2025-11-25

Technology stack

• ASP.NET Core 10.0 - Minimal API for API development, with following base services:

  • Resilience for resilience when calling downstream APIs

  • Compliance for redacting sensitive data

  • Health checks for checking health status

  • Service Discovery for resolving endpoints from config

  • Hybrid Cache for caching

  • Rate limiting for rate limiting

  • API Key, JWT bearer and OpenID Connection-based authentication for security, with:

    • token reuse prevention for Entra ID tokens

  • OpenApi for generating OpenAPI specifications

  • Cross-Origin Resource Sharing (CORS) for cross-origin requests

  • Validation for validating requests on endpoints

• OpenTelemetry (OTel) for observability

• Aspire for development bootstrapping and client integrations

• Kiota API client generation for calling downstream APIs

• Gridify for filtering, ordering and paging

• Scalar for interactive API documentation

• Spectral for linting

• TUnit for unit tests

• REST Client extension in Visual Studio Code for quick local tests via .http files

• MCPify for exposure via Model Context Protocol

• CloudEvents for event delivery

Design

Technically, the design is layered like the following flowchart.

flowchart TB

apis[BankApi.Service.Beta / BankApi.Service.Stable]
aspire[BankApi.Orchestration]
mcp[BankApi.Mcp]
test[BankApi.Tests]

infra_gen[Infra.Generated]
specs_gen[Specs.Generated]

subgraph core[BankApi.Core]
Defaults
DownstreamClients
Implementation
end

Defaults --> Implementation

DownstreamClients --> Defaults
DownstreamClients --> Implementation

Defaults --> apis
Implementation --> apis
Implementation --> test

apis --> aspire
apis --> specs_gen

aspire--> infra_gen
specs_gen --> mcp

Prerequisites

If not using the Dev Container, install:

• .NET 10 SDK

• All recommended Visual Studio Code extensions

Quick start

• Use a pwsh shell (for a click-a-long experience).

• (Optionally) regenerate the GitHub downstream API client by going to the Kiota workspace and clicking Re-generate under clients.

  

• (Optionally) regenerate the ASP.NET Core HTTPS development certificate:

  dotnet dev-certs https --clean && dotnet dev-certs https -ep ./.certs/AspNetDev.pfx -p '' --trust
  

• (Optionally) regenerate the Aspire manifest:

  dotnet run --project BankApi.Orchestration --publisher manifest --output-path ../Infra.Generated/aspire-manifest.json
  

• Generate a new JWT-token for secured endpoints:

  dotnet user-jwts create --scope "bank_api" --role "banker" --valid-for 3650d --project BankApi.Service.Stable
  

• Run dotnet build to output the OpenAPI definition. Make sure the local environment for ASP.NET Core points to development:

  setx ASPNETCORE_ENVIRONMENT "Development"
  

• Validate the OpenAPI definition by going to the openapi_v1.json definition and check for problems via the Spectral extension.

Container images

Create a pod:

podman pod create --name bank-api-pod -p 8080:8080 -p 5201:10000

Start the OpenTelemetry Collector to process and export telemetry data:

podman build -t bank-api-otelcol:v1 ./Sidecar.OpenTelemetry --tls-verify=false
podman run --pod bank-api-pod bank-api-otelcol:v1

Rename the env sample file to .env and replace the values, then run the following to build and start an Alpine with Composite ready-to-run image with ready-to-run API:

podman build -t bank-api:v1 .
podman run --pod bank-api-pod --env-file .env bank-api:v1

To facade the API as well, start the Proxy:

podman build -t bank-api-proxy:v1 ./Sidecar.Proxy --tls-verify=false
podman run --pod bank-api-pod bank-api-proxy:v1

Then navigate to the proxied OpenAPI Spec or Scalar UI, or use :8080 to directly call the API.

Run in Aspire minimal mode

This mode just runs the ASP.NET Core API.

1. Make sure a container runtime is started.

2. Start the standalone Aspire Dashboard for developer visualization:

   podman run --rm -it `
     -p 18888:18888 `
     -p 4317:18889 `
     --name aspire-dashboard `
     mcr.microsoft.com/dotnet/aspire-dashboard:latest
   

   Copy the url shown in the resulting output when running the container (e.g. <http://localhost:18888/login?t=123456780abcdef