Bank API 🏦

[![CC BY-NC-SA 4.0][cc-by-nc-sa-shield]][cc-by-nc-sa]

The Bank API is a design reference project suitable to bootstrap development for a compliant and modern API.

Explore the live 🌐 API with sidecars and 🌐 MCP server (both hosted on Azure Container Apps).

Compliance

API

✅ OWASP API Security Top 10 - v2023 via Spectral OWASP API Security ruleset

✅ OpenAPI Specification v3.2.0 via Spectral "oas" ruleset

✅ NLGov (Dutch Public Sector) REST API Design Rules 2.2.1 via API Design Rules ruleset

✅ Additional naming conventions, structure, and clarity via Bank API project ruleset

✅ California Consumer Privacy Act (CCPA) and General Data Protection Regulation (GDPR) via ASP.Net Core Compliance

✅ 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.2.0 - 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 11.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 11 SDK

• All recommended Visual Studio Code extensions

• Aspire CLI:

  irm https://aspire.dev/install.ps1 | iex
  

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 Helm chart artifacts via the Aspire CLI:

  rm -r Infra.Generated/* && aspire --version && aspire publish -o Infra.Generated
  

• 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_spec.json definition and check for problems via the Spectral extension.

Container images

A complete orchestration of all containers with Kube Resource Orchestrator (kro) is available at Infra.Kro. To setup all the containers step-by-step with podman, follow the below steps:

Rename the env sample file to .env and replace the values.

Create a pod:

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

Start the Dapr sidecar to expose secret stores, explore via the metadata endpoint or check a secret:

podman build -t bank-api-daprd:v1 ./Sidecar.Dapr
podman run --pod bank-api-pod --env-file .env bank-api-daprd:v1

Start the OpenTelemetry Collector to process and export telemetry data:

podman build -t bank-api-otelcol:v1 ./Sidecar.OpenTelemetry
podman run --pod bank-api-pod --env-file .env bank-api-otelcol:v1

Start the S3Proxy sidecar to expose Azure Blob Storage as an S3-compatible endpoint:

podman build -t bank-api-s3proxy:v1 ./Sidecar.S3Proxy
podman run --pod bank-api-pod --env-file .env bank-api-s3proxy:v1

Start the Stable version of the API as an [Alpine with Composite ready-to-run image](https://github.com/dotnet/dotnet-docker/tree/main/samples/aspnetapp#supported-linux-distros:~:text=Alpine%20with%20Composite%20read