Reference Architecture: OpenAPI Backend

Status: Proposed | Date: 2025-07-28

When to Use This Pattern

Use when you need clear separation between user-facing and administrative operations in REST APIs requiring structured documentation and testing.

Overview

Template for implementing OpenAPI-first API services with complete separation between user-facing and administrative operations.

Core Components

API Clients -> Edge Protection -> Routing

Routing -> Standard APIs: api.domain Routing -> Admin APIs: admin.domain

Standard APIs: { style: { fill: “#e3f2fd” stroke: “#1565c0” } }

Admin APIs: { style: { fill: “#ffebee” stroke: “#c62828” } }

Standard APIs -> User Database Admin APIs -> System Database Admin APIs -> User Database: admin access Standard APIs (/api/v1/*): Business operations for authenticated users

• Examples: /api/v1/users/profile, /api/v1/orders, /api/v1/documents
• Domain: api.domain with Standard Realm authentication

Administrative APIs (/admin/v1/*): System management for privileged users

• Examples: /admin/v1/users, /admin/v1/system/config, /admin/v1/audit-logs
• Domain: admin.domain with Admin Realm authentication

Complete Separation: Two separate routers provide full network and authentication isolation between standard and administrative operations per ADR 013: Identity Federation Standards.

Project Kickoff Steps

1. Infrastructure Foundation - Follow ADR 001: Application Isolation and ADR 002: AWS EKS for Cloud Workloads
2. API Standards - Follow ADR 003: API Documentation Standards for OpenAPI specification
3. Identity Federation - Follow ADR 013: Identity Federation Standards for domain separation
4. Edge Protection - Follow ADR 016: Web Application Edge Protection for rate limiting and security
5. Database & Secrets - Follow ADR 018: Database Patterns and ADR 005: Secrets Management
6. Logging & Monitoring - Follow ADR 007: Centralized Security Logging for audit trails