bank-api

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.

See the APIs.json (v0.21) compliant documentation.

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:

  powershell复制

  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:

  bash复制

  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:

  bash复制

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

• Generate a new JWT-token for secured endpoints:

  bash复制

  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:

  bash复制

  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 with ready-to-run format:

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
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 podman pod rm -f bank-api-pod to teardown.

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:

   bash复制

   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. ) and open that in a browser, or paste the key part seen after /login?t= when the login dialog is shown. The token will change each time the container is started.

3. Run the launch config API - Stable release channel.

Run in Aspire mode

This mode starts the Stable and Beta versions of the API with required sidecars, including an MCP server for the Stable version, in context of Aspire.

1. Make sure a container runtime is started and Aspire is set to use that runtime (if using anything other than docker):

   bash复制

   podman machine start
   setx ASPIRE_CONTAINER_RUNTIME "podman"

2. Run the launch config Aspire Orchestration.

Run the MCP server

The MCP server is designed to run on HTTP Stream Transport, separately from the API, based on the OpenAPI specification generated by the API.

Currently, it registers t