API Reliability Suite

Backend-focused FastAPI reliability reference with health checks, auth, metrics, and failure handling.

A small FastAPI service that demonstrates backend reliability patterns without requiring external AI providers.

Why This Exists

Many FastAPI examples stop at routes and CRUD flows. This repository focuses on a small, runnable set of operational behaviors: health, readiness, authentication, rate limiting, metrics, and circuit-breaker fallback.

Evidence

Artifact	Status
CI matrix	Passing on Python 3.12 and 3.13: CI run
Container security scan	Passing SBOM + Grype scan after OpenSSL, Mako, and python-multipart fixes: Security run
Documentation deploy	Passing GitHub Pages build/deploy: Docs run
Local test suite	59 passed with patched dependency set
Observability proof	Prometheus metrics and structured logs

What's Included

This repository contains a working FastAPI application plus supporting local observability services.

Backend:

• JWT-based login, refresh-token rotation, logout, and protected routes
• Relational user persistence backed by SQLAlchemy with Postgres-ready configuration
• Separation between request handling, services, and infrastructure adapters
• Config-driven token expiry, role-aware auth, and request-level RBAC

DevOps:

• Route-level rate limiting with SlowAPI
• Alertmanager-ready local alerting plus SLO-oriented Prometheus recording rules
• Prometheus metrics plus auto-provisioned Grafana dashboards and Jaeger for local observability
• Circuit-breaker behavior with Redis-backed fallback caching
• Structured logging with correlation IDs and trace context

Diagnostics:

• Local error-count and latest-error summary from structured logs

Requirements

• Python 3.12 or 3.13
• Poetry
• Docker with Compose support for the local observability stack

Quickstart

git clone https://github.com/darestack/api-reliability-suite.git
cd api-reliability-suite

make install
make run

The API will be available at http://localhost:8000.

Swagger UI is available at http://localhost:8000/docs.

For local exploration, a demo user is available:

• Username: demo
• Password: secret123

Project Scope

This project is best treated as a template or reference implementation rather than a finished production system.

Current boundaries:

• SECRET_KEY defaults to a demo value and must be replaced for real deployments.
• Local make run defaults to SQLite unless DATABASE_URL is set; the Docker Compose stack uses Postgres.
• Rate limiting uses in-memory storage by default unless RATE_LIMIT_STORAGE_URI is set (the Docker Compose stack uses Redis).
• /external-api returns the most recent cached upstream payload when the breaker is open and Redis fallback caching is configured.
• /debug/summarize-errors is restricted to admin users and reads the configured log file locally.
• /ready performs dependency-aware checks for the database and configured Redis-backed features.
• When ENVIRONMENT is set to staging or production, the app requires a non-default SECRET_KEY, a shared RATE_LIMIT_STORAGE_URI, and a server-grade DATABASE_URL.

Local Observability Stack

make stack-up

Services:

Service	URL
API	http://localhost:8000
Prometheus	http://localhost:9099
Alertmanager	http://localhost:9093
Grafana	http://localhost:3030
Jaeger	http://localhost:16686
Postgres	postgres://app:app@localhost:5432/reliability_suite
Redis	redis://localhost:6379

Grafana default login: admin / admin Provisioned dashboard: http://localhost:3030/d/api-reliability-slo

Optional components

Not every use case needs the full stack. Here's what you can skip:

Component	Skip if...	Core alternative
Jaeger	You don't need distributed trace visualization	Remove from compose.yml; structured logs still include trace IDs
Alertmanager	You don't need alert routing / notification channels	Prometheus rules still fire; just no forwarding
Redis	You don't need rate limiting or circuit-breaker fallback cache	Set RATE_LIMIT_STORAGE_URI empty; breaker still works without cache
Local error summary	You only need deterministic diagnostics	/debug/summarize-errors remains admin-only

Minimum viable setup: make run (SQLite + in-memory rate limiting). No Docker required.

If Postgres or Redis are already bound on your machine, override the host ports:

POSTGRES_PORT=15432 REDIS_PORT=16379 docker compose up -d

Configuration

Create a .env file or export environment variables for the settings you want to override.

Common settings:

• ENVIRONMENT
• DATABASE_URL
• SECRET_KEY
• ACCESS_TOKEN_EXPIRE_MINUTES
• REFRESH_TOKEN_EXPIRE_DAYS
• RATE_LIMIT_STORAGE_URI
• CIRCUIT_BREAKER_CACHE_URL
• RATE_LIMIT_HEADERS_ENABLED
• RATE_LIMIT_KEY_PREFIX
• TRUSTED_HOSTS
• CORS_ALLOW_ORIGINS
• HTTPS_REDIRECT_ENABLED
• SETTINGS_SECRETS_DIR
• OTLP_ENDPOINT
• PROMETHEUS_BASE_URL
• LOG_FILE_PATH

The structured log file path defaults to app.json. Docker and Kubernetes secret files are supported by setting SETTINGS_SECRETS_DIR (defaults to /run/secrets if present). Shared deployments should also set TRUSTED_HOSTS, terminate TLS at a reverse proxy or ingress, and enable HTTPS_REDIRECT_ENABLED behind that proxy.

API Overview

Endpoint	Method	Purpose
/health	GET	Health check with rate limiting
/ready	GET	Dependency-aware readiness for DB and Redis
/login	POST	Exchange credentials for an access and refresh token
/token/refresh	POST	Rotate a refresh token and issue a fresh token pair
/logout	POST	Revoke the current access token and optional refresh token
/protected	GET	Example authenticated route
/external-api	GET	Circuit-breaker demo endpoint with cache-backed fallback support
/debug/summarize-errors	GET	Admin-only local error summary
/slo/report	GET	Report SLO targets and Prometheus-backed recording-rule values when configured
/slow	GET	Simulate latency for tracing demos
/force-error	GET	Trigger a 500 error for alerting and debugging demos

For more detail, see API Reference.

Development

make lint
make format
make test
make load-test

Focused verification:

poetry run pytest -q --no-cov tests/test_auth.py tests/test_api.py tests/test_reliability.py

Documentation

Live docs: https://darestack.github.io/api-reliability-suite/

Run docs locally:

poetry run mkdocs serve

• Architecture & Internals
• Monitoring & Metrics
• Load Testing
• Development Guide
• Configuration Guide
• Security Guide
• Security Policy
• Production Checklist

GitHub Metadata

Suggested repo description: FastAPI reliability reference with auth, rate limiting, metrics, and circuit-breaker fallback.

Suggested topics: fastapi backend devops observability prometheus rate-limiting circuit-breaker jwt

Support

• Documentation: https://darestack.github.io/api-reliability-suite/
• Issues: https://github.com/darestack/api-reliability-suite/issues
• Maintainer: adelekedare2012@gmail.com | LinkedIn