Backend Architecture · API Risk Analysis Engine
API Change Radar
A production-minded FastAPI backend service that parses and validates OpenAPI specifications, calculates deterministic AST differences, classifies compatibility risks, and stores reports in PostgreSQL.
Overview
API contract modifications often trigger silent integration breakages and release risks. Standard textual diff outputs are cluttered with whitespace, indentation, or field-sorting differences, failing to evaluate semantic contract changes. API Change Radar targets this challenge by parsing specifications into normalized AST trees, calculating deterministic differences, and flagging breaking release risks.
Designed as a production-minded portfolio project, API Change Radar is not a simple script; it is a persistent backend service. It manages upload files, performs asynchronous analysis runs, logs operations with structured database tracking, monitors execution metrics via OpenTelemetry, and exposes results in JSON, Markdown, or an HTML review dashboard.
Full JSON and YAML specification parsing, reference resolution, and syntax validation
SQLAlchemy + Alembic relational model database for specifications and run persistence
AST-based comparison tree isolating changes from formatting noise
Distributed request tracing, structured logging, health nodes, and Prometheus metrics
The Problem
API contract changes break consumers silently.
When API teams delete paths, rename parameters, or add required fields, downstream consumers break silently. These breakages are often caught only in production. Standard git textual differences show formatting and comment changes, masking the actual API contract changes. Developers need a deterministic service that validates contracts, assigns severity categories, and exposes structured reviews.
Key Features
Deterministic Spec Parsing. Parses OpenAPI YAML and JSON, resolving complex $ref nodes and catching syntax errors before comparisons.
Compatibility Checks. Identifies critical breaking changes (e.g., deleted endpoints, altered request types, added required fields).
History Persistence. Saves run metadata, upload files, canonical AST snapshots, and compatibility audits in PostgreSQL database.
Multi-format Reports. Exposes structural JSON for CI/CD gates, alongside readable Markdown change logs and a visual HTML report.
Distributed Telemetry. Features transaction correlation IDs, integrated logs, health/readiness endpoints, and Prometheus outputs.
Docker-First Setup. Pre-configured end-user Docker compose file pulling prebuilt application images directly from Docker Hub.
Quick Start
Docker-first distribution workflow.
The project is packaged for end users: pull the prebuilt image from Docker Hub and launch the PostgreSQL database and FastAPI server with Docker Compose.
Clone the repository or download the ZIP file and open the project directory in your terminal.
Copy .env.example to .env to configure application port, database users, and logging levels.
Run `docker compose up -d` to pull the Postgres and API image, run database migrations, and boot the server.
Verify database and container readiness by visiting `/healthz` or the Swagger UI interactive docs at `/docs`.
Submit specs to `/api/v1/runs`, check status, and retrieve Markdown or HTML demo dashboards.
System Architecture
Pipeline modules and service components.
Accepts spec files (JSON/YAML) and optional changelog text, generating UUID transaction tags.
Resolves spec schemas, catches structural syntax errors, and validates files are non-empty.
Converts specification maps into standard internal representations to remove formatting noise.
Computes AST-level differences for endpoints, parameters, request body schemas, and response maps.
Classifies findings into compatibility buckets (Safe, Warning, Breaking) based on API principles.
Stores specification versions, canonical snapshots, and structured findings in PostgreSQL.
Exposes structural JSON data, downloads Markdown formats, or serves the HTML demo review dashboard.
Instruments the runtime with request correlation tracing, structured logs, and Prometheus metrics.
API Documentation
Clean and RESTful API endpoints.
The service is fully documented with Swagger UI at `/docs` and ReDoc at `/redoc`, allowing users to submit specs and query compatibility.
| Method | Endpoint Path | Request Input | Description & Operation |
|---|---|---|---|
| POST | /api/v1/runs | specs (2 files), optional changelog_text | Initiates a specification comparison run in the background. |
| GET | /api/v1/runs/{run_id} | run_id | Checks the processing status of the background analysis run. |
| GET | /api/v1/reports/{report_id} | report_id | Retrieves the structured JSON report containing all API changes. |
| GET | /api/v1/reports/{report_id}?format=markdown | report_id, format=markdown | Generates and downloads a Markdown version of the API changes changelog. |
| GET | /api/v1/reports/{report_id}/demo | report_id | Serves the visual demo HTML review page for human inspection. |
| GET | /healthz | /readyz | None | Exposes endpoints for container orchestration readiness checks. |
| GET | /metrics | None | Exposes application performance telemetry and request counts. |
Configuration
Environment configurations.
Settings are managed via env vars, defaulting to safe production options. Override variables in your `.env` configuration.
| Variable | Default / Example | Description |
|---|---|---|
APP_PORT | 8000 | Host port mapped to the FastAPI container application. |
POSTGRES_USER / DB | radar / api_change_radar | User credentials and database name in PostgreSQL. |
DEBUG | false | Enables verbose debug mode and stack traces in API responses. |
LOG_LEVEL | INFO | Sets logging thresholds (DEBUG, INFO, WARNING, ERROR). |
ENABLE_LLM_CHANGELOG | false | Feature flag activating optional AI-based natural language summaries. |
LLM_CONFIDENCE_THRESHOLD | 0.6 | Confidence threshold below which the optional AI summary falls back. |
Design Principles
Engineering decisions.
Deterministic Logic First
Changes are computed using mathematical AST-level differences rather than non-deterministic models.
Explicit over Clever
Code structures prioritize readability, simple control flows, and strict types over magic decorators.
Narrow Scope First
Avoids premature integrations; focuses on doing specification analysis correctly first.
Built-in Observability
Telemetry, request tracking IDs, and metrics are integrated into the core service design.
AI is Non-Authoritative
Generative layers are optional, isolated, and never override the deterministic diff result.
Database Migrations (Alembic)
Migrations run automatically on container startup. For manual upgrades or outside Docker environments, use the following Alembic CLI commands:
alembic upgrade head alembic downgrade base Boundary Definition
MVP scope vs. intentional non-goals.
To prevent scope creep, the project keeps a clean boundary. The initial release focuses on core parsing and persistence.
| Functional Area | Supported in MVP | Intentional Non-Goal |
|---|---|---|
| Upload parsing | JSON and YAML file formats parsed and verified | Remote URL spec fetching or automatic downloading |
| Integrations | Swagger docs, curl commands, and local scripts | Direct GitHub webhooks or Slack notification alerts |
| Interface | FastAPI interactive docs and HTML demo dashboard | Multi-page react frontend or custom editor suites |
| Access control | Single-user local environment runs | Multi-tenant authentication, RBAC, or user workspaces |
| AI role | Summarizes changes without editing diff outputs | Automatic decisions, AI-driven merges, or auto-fixing specs |
My Contribution
I designed and coded the FastAPI backend service, establishing endpoints for YAML/JSON uploads. I built the SQLAlchemy PostgreSQL persistence layer, configured migrations via Alembic, and developed the deterministic AST comparison rules that classify contract breakages. Additionally, I structured the container setups, transaction metrics, and request tracing models.
Technology Stack