API Sentinel 🛡️
API Sentinel (api-drift-detector) is an asynchronous FastAPI / ASGI middleware and developer telemetry dashboard that detects real-time contract drifts between runtime API payloads and your OpenAPI specification.
🚀 Key Features
- ⚡ Zero-Latency Async Interception: Uses non-blocking background tasks (
asyncio.create_task) and request buffering so your API responses stream immediately without waiting for validation. - 🔍 Comprehensive Drift Detection: Detects missing required fields, undocumented query/path parameters, type mismatches, undocumented HTTP status codes, and extra fields.
- 📊 Real-Time Developer Dashboard: Built-in interactive dashboard with live polling, KPI metrics, pass/fail rate timeline charts, and severity breakdowns.
- 💾 Database Persistence: Automatically records validation history and schema diffs to SQLite via SQLAlchemy (
aiosqlite), persisting telemetry across server restarts. - 🪄 OpenAPI Specification Wizard: Visual form-based generator to design, preview, test, and save OpenAPI specs directly from the browser.
- 💻 CLI Tooling: Built-in
api-drift-detector(andapi-sentinel) command-line interface to launch dashboards and validate specifications.
📦 Installation
From PyPI (Recommended):
pip install api-drift-detector
From GitHub (Latest source):
pip install git+https://github.com/T41h4X/API_sentinel.git
⚡ Quick Start
1. Launch the Sentinel Dashboard (Terminal 1)
Start the monitoring dashboard on port 8001:
api-drift-detector dashboard
(or use api-sentinel dashboard)
Open your browser at http://127.0.0.1:8001 to monitor incoming traffic, validation results, and contract drifts in real time.
2. Integrate Middleware in Your FastAPI App (Terminal 2)
Add APISentinelMiddleware to your FastAPI application:
from fastapi import FastAPI
from api_sentinel import APISentinelMiddleware
app = FastAPI(title="My API")
# Register Sentinel Middleware
app.add_middleware(
APISentinelMiddleware,
openapi_path="openapi.yaml", # Path to your OpenAPI spec
dashboard_url="http://127.0.0.1:8001", # URL of the Sentinel dashboard
enabled=True,
print_clean=True,
)
@app.get("/api/v1/users/{user_id}")
async def get_user(user_id: int):
# Any schema mismatch or extra undocumented fields will trigger live alerts!
return {"id": user_id, "name": "Alice"}
Run your FastAPI server on port 8000:
uvicorn app:app --reload --port 8000
Any request sent to your FastAPI server (http://127.0.0.1:8000/api/v1/users/1) is intercepted, checked against openapi.yaml, and streamed directly into your dashboard!
💻 Command Line Interface (CLI)
The package provides the api-drift-detector (and api-sentinel) CLI:
# Start the monitoring dashboard (default: http://127.0.0.1:8001)
api-drift-detector dashboard
# Start on custom host or port
api-drift-detector dashboard --host 0.0.0.0 --port 8080
# Start dashboard in development mode with auto-reload
api-drift-detector dashboard --reload
# Validate an OpenAPI specification file in CI/CD pipelines
api-drift-detector validate --spec openapi.yaml
# Check installed version
api-drift-detector version
⚙️ Configuration
API Sentinel can be configured using environment variables (prefixed with SENTINEL_) or a .env file:
| Variable | Default | Description |
|---|---|---|
SENTINEL_DATABASE_URL |
sqlite+aiosqlite:///./sentinel.db |
SQLAlchemy database connection string |
SENTINEL_RETENTION_DAYS |
30 |
Number of days to retain validation records before cleanup |
SENTINEL_MASKED_FIELDS |
["password", "token", "credit_card", "authorization"] |
Sensitive payload fields automatically masked |
SENTINEL_SELECTIVE_PERSISTENCE |
false |
When true, only saves WARNING and FAILED validation results |
SENTINEL_OPENAPI_SPEC_PATH |
openapi.yaml |
Default OpenAPI specification file path |
🧪 Running the Demo Locally
Clone the repository and test the full demo application with sample drifts:
git clone https://github.com/T41h4X/API_sentinel.git
cd API_sentinel
# Create and activate environment
python -m venv .venv
.\.venv\Scripts\activate # Windows
source .venv/bin/activate # Linux / macOS
# Install package
pip install -e .
# Launch all demo services (Windows)
start_all.cmd
📄 License
This project is licensed under the MIT License - see the LICENSE file for details.
Metadata
Release files for api-drift-detector 0.1.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| api_drift_detector-0.1.3.tar.gz | 114.3 kB | Without provenance | Details for api_drift_detector-0.1.3.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| api_drift_detector-0.1.3-py3-none-any.whl | Python 3 | none | any | Details for api_drift_detector-0.1.3-py3-none-any.whl |
Total release size: 193.2 kB
Release files / api_drift_detector-0.1.3.tar.gz
| Download URL | api_drift_detector-0.1.3.tar.gz |
|---|---|
| Size | 114.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
438300b29c7c3e9d97bfd77fc05cf6d636b7600f6b7df1087caa21edaf69bac5
|
|
BLAKE2b-256 checksum How to use checksums |
15f896cc36e19239cce54ca683a7681c1f14ca29cf44a35fc40c488991b6c2c2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.9
|
Release files / api_drift_detector-0.1.3-py3-none-any.whl
| Download URL | api_drift_detector-0.1.3-py3-none-any.whl |
|---|---|
| Size | 78.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
7f77546515df5aac912d259235e3bfc4070d00c6d26b12837925e7e200470dd9
|
|
BLAKE2b-256 checksum How to use checksums |
5bf64693b03789091c7cf035bd8ef56060cc767e8d1e75e26686787a032b6351
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.9
|
Security for api-drift-detector 0.1.3
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.