api-shield 0.2.0

Route lifecycle management for APIs — maintenance mode, env gating, deprecation, and more

Route lifecycle management for Python web frameworks — maintenance mode, environment gating, deprecation, admin panels, and more. No restarts required.

---

Install

uv add "api-shield[all]"
# or: pip install "api-shield[all]"

Quickstart

from fastapi import FastAPI
from shield.core.config import make_engine
from shield.fastapi import (
    ShieldMiddleware, ShieldAdmin, apply_shield_to_openapi,
    maintenance, env_only, disabled, force_active, deprecated,
)

engine = make_engine()

app = FastAPI()
app.add_middleware(ShieldMiddleware, engine=engine)

@app.get("/payments")
@maintenance(reason="DB migration — back at 04:00 UTC")
async def get_payments():
    return {"payments": []}

@app.get("/health")
@force_active
async def health():
    return {"status": "ok"}

apply_shield_to_openapi(app, engine)
app.mount("/shield", ShieldAdmin(engine=engine, auth=("admin", "secret")))

GET /payments  → 503  {"error": {"code": "MAINTENANCE_MODE", ...}}
GET /health    → 200  always

Manage routes from the CLI — no code changes, no restarts:

shield config set-url http://localhost:8000/shield
shield login admin
shield status
shield enable GET:/payments
shield global enable --reason "Deploying v2" --exempt /health

Decorators

Decorator	Effect	Status
@maintenance(reason, start, end)	Temporarily unavailable	503
@disabled(reason)	Permanently off	503
@env_only("dev", "staging")	Restricted to named environments	404 elsewhere
@deprecated(sunset, use_instead)	Still works, injects deprecation headers	200
@force_active	Bypasses all shield checks	Always 200

Backends

Backend	Persistence	Multi-instance
MemoryBackend	No	No
FileBackend	Yes	No
RedisBackend	Yes	Yes

---

Documentation

Full documentation at attakay78.github.io/api-shield

Tutorial	Get started in 5 minutes
Decorators reference	All decorator options
ShieldEngine reference	Programmatic control
Backends	Memory, File, Redis, custom
Admin dashboard	Mounting ShieldAdmin
CLI reference	All CLI commands
Production guide	Monitoring & deployment automation

License

MIT