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.
Live Deployment & Containerization. Deployed live on Render with full API metrics, and packaged with Docker Compose for localized scaling and testing.
Live Playground
Swagger interactive console.
The service runs fully deployed on Render with an active PostgreSQL database. You can inspect endpoints and execute diff runs directly from the browser.
https://api-change-radar.onrender.com/api/v1 This demo runs on Render Free. If the service has been idle, the container enters sleep mode. The first request may take up to 60 seconds while the server spins up.
Try It Yourself
Swagger-based analysis walk-through.
Test the live API contract validation engine in 5 quick steps without setting up any local dependencies.
Access the interactive documentation and click "Try it out" on the endpoints.
Provide two OpenAPI specifications (e.g., examples/v1.yaml and examples/v2.yaml) to POST /api/v1/runs.
Execute the request to trigger the deterministic AST diff engine and receive a run_id.
Check GET /api/v1/runs/{run_id} to monitor the processing state until it is completed.
Fetch the structured change audit via GET /api/v1/reports/{run_id} or render the dashboard via /demo.
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.
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.
My Contribution
I architected and implemented the FastAPI backend, designing the AST-based diff engine for deterministic OpenAPI schema comparisons. I established the relational database schema, Alembic migration workflow, and upload validation pipelines. I also set up the production containerization with Docker Compose, integrated full distributed tracing with OpenTelemetry, and deployed the live service to Render with active health checks and metrics monitoring.
Technology Stack