Bank API 🏦

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

Explore the live 🌐 API and 🌐 MCP server. Hosted on F1 tier Azure App Service, so mileage may vary.

Compliance

API

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

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

✅ Dutch Public Sector (NLGov) REST API Design Rules 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.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 image

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:

podman build -t bankapi:v1 .
podman run -p 5201:8080 --env-file .env bankapi:v1

Then navigate to the OpenAPI Spec or Scalar UI.

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=123456780abcdef123456780) 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, including an MCP server for the Stable version, in context of Aspire.

1. Make sure a container runtime is started.

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 tools for operations via API Key and OAuth Authorization Code authentication methods.

Make sure to run BankApi.Service.Stable, and BankApi.Mcp at the same time. The easiest way is to just Run in Aspire mode.

Claude

Configure your claude_desktop_config.json with the following mcpServers entry:

{
  "mcpServers": {
    "bankApi": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://bankapi-mcp-001-ctcahwhschgrdqb4.westeurope-01.azurewebsites.net",
        "--allow-http",
        "--debug"
      ]
    }
  }
}

Replace the URL with http://localhost:5200 when using the local MCP server.

GitHub Copilot

To host the MCP server, make sure to Authorize Visual Studio Code in the app registration.

Considerations

General

1. OpenID Connect isn't fully supported in Scalar.

2. To extend OpenTelemetry logging to Application Insights, expand the OpenTelemetry exporter.

3. The compliance NullRedactor doesn't seem to work, the redactor is already defined at Builder.Compliance.cs but not used because of the issue.

4. Dependabot is enabled for nuget packages but wildcard version notation isn't supported yet, which is used extensively in this project.

5. The OpenAPI document generator shipped with .NET 10 does not fully support API versioning, a simpler approach with PathBase is used for now, which is also more convenient for Azure API Management usage.

6. Extending Spectral rulesets from an NPM package can be problematic.

7. Generic exception handling is minimally implemented via ErrorHandling.cs.

8. API owners usually have customers outside of their own company - or outside of their own domain within a company - which inherently means adoption time will be slower for API contract changes, this is why there is a Stable and Beta version of the API in this project, inspired by the Microsoft Graph API Current/Beta versioning design. New or modified contract-breaking (beta) operations to API consumers may be served via the Beta version without distracting users on the Stable version.

   Do not confuse this versioning scheme as a replacement for DTAP; it is merely complementary to it. Many API changes will affect both the Stable and Beta endpoints (such as changes to the underlying shared database). That's why they both share a common layer in the form of BankApi.Core.

   Nonetheless, versioning is very opinionated and one should always see what the best business and technical fit is. This might change over time and from project to project.

9. Dev Containers with the docker-outside-of-docker feature instead of docker-in-docker do not work, for now we're using docker-in-docker.

Please see the Reddit r/dotnet post 1 and post 2 about this project for more considerations and information.

Troubleshooting

• If debugging isn't working properly, please clear the Extension Host Cache at %AppData%\Code\CachedData (on Windows) and restart VSCode.

• If getting the error unable to get local issuer certificate with Spectral, make sure to add the CA of the proxy to NODE_EXTRA_CA_CERTS and restart VSCode, for example:

setx NODE_EXTRA_CA_CERTS "C:\ZscalerRootCA.crt"

• Extending Rulesets with local filepath not refreshing when working on Spectral rulesets in VSCode. Force an update in Specs.Ruleset/main.yml when changing a file that is used as an extend.

License

This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.