← All skills

Most APIs fail on the same five things: unclear contracts, no authorisation model, no idempotency, no pagination discipline, and no observability. This skill closes all five before launch.

When to use this skill

• Building a new REST API that will serve a real client.
• Adding endpoints to an existing service.
• Hardening a prototype API before exposing it.

Stage 1 - Contract before code

Write the OpenAPI shape first, or the resource table:

Rules that prevent rewrites: version in the path (/v1), plural nouns, no verbs in paths, snake_case JSON, ISO-8601 UTC timestamps, ids as UUID or ULID strings, money as integer minor units plus a currency code (never floats).

Stage 2 - Project layout

app/
  main.py            app factory, middleware, routers
  core/              config, security, logging, errors
  db/                engine, session, migrations
  models/            SQLAlchemy models
  schemas/           pydantic request/response models
  api/v1/            routers per resource
  services/          business logic - no HTTP here
  tests/

Hard rule: routers validate and delegate; services contain logic; models touch the database. No SQL in a router, no Request object in a service.

Stage 3 - Validation and error model

from pydantic import BaseModel, EmailStr, Field
class UserCreate(BaseModel):
    email: EmailStr
    name: str = Field(min_length=1, max_length=80)
    plan: Literal["free", "pro"] = "free"

One error envelope for the whole API, always:

{"error": {"code": "email_taken", "message": "That email is already registered.",
           "field": "email", "request_id": "req_01H..."}}

• 400 malformed, 401 unauthenticated, 403 not permitted, 404 absent, 409 conflict, 422 semantic validation, 429 rate limited, 500 unexpected.
• Never leak stack traces, SQL or internal ids to clients. Log them with the request_id instead.
• Error code is a stable machine string; message is human and safe to show.

Stage 4 - Auth and authorisation

1. Authentication: bearer JWT or opaque session in an httpOnly cookie. Short-lived access token (15 min) + refresh token rotation.
2. Passwords: argon2id, never bcrypt-with-default-cost, never MD5/SHA.
3. Authorisation: a dependency that loads the resource and checks ownership or role on the server, per endpoint. A check in the UI is not a check.

def get_owned_order(order_id: str, user=Depends(current_user), db=Depends(get_db)) -> Order:
    order = db.get(Order, order_id)
    if not order:
        raise HTTPException(404, "order_not_found")
    if order.user_id != user.id and not user.is_admin:
        raise HTTPException(403, "forbidden")
    return order

1. Rate limit per user and per IP on auth and write endpoints. 429 with Retry-After.
2. Never trust client-supplied role, price, total or user id. Derive them server-side.

Stage 5 - Idempotency and safety on writes

• Accept Idempotency-Key on POST that creates money or state. Store key -> response for 24h; replay returns the same response.
• Wrap multi-step writes in a transaction. Commit once, at the end.
• Use SELECT ... FOR UPDATE or an optimistic version column where concurrent updates matter.
• Soft-delete with deleted_at when recovery or audit is needed; hard-delete for genuine privacy requests.

Stage 6 - Pagination, filtering, sorting

@router.get("/orders")
def list_orders(cursor: str | None = None, limit: int = Query(20, le=100), ...):

• Cursor pagination for feeds and anything that changes while paging; offset for admin tables.
• Cap limit at 100. Reject unknown sort fields against an allowlist - never interpolate into SQL.
• Return {"data": [...], "next_cursor": "..."}. Never return an unbounded array.

Stage 7 - Database and migrations

• Alembic (or equivalent) from commit one. Never create_all() in production.
• Every migration is reversible; test the downgrade once.
• Index every foreign key and every column you filter or sort on. Verify with EXPLAIN.
• Add NOT NULL columns with a default, backfill, then drop the default - in three steps, not one.
• Connection pooling sized to the database's limit, not to hope.

Stage 8 - Tests

1. Unit tests for services with a fake repository - fast, no DB.
2. Integration tests against a real ephemeral Postgres (testcontainers or a docker service) - catches what mocks hide.
3. Contract tests: every endpoint's success and error shape asserted against the OpenAPI schema.
4. Auth tests: unauthenticated, wrong user, admin, expired token, for each protected route.
5. One load smoke test at 10x expected traffic on the heaviest read path.

Target: the auth-and-write paths have 100% of their branches covered. Chasing a global coverage number is theatre.

Stage 9 - Observability and operations

• Structured JSON logs with request_id, user_id, route, status, duration_ms.
• /healthz (liveness) and /readyz (dependencies reachable).
• Metrics: p50/p95/p99 latency per route, error rate, queue depth, DB pool saturation.
• Tracing across the API and any downstream calls.
• Sentry with release tags and source maps where relevant.

Stage 10 - Deploy checklist

• Secrets in the platform's secret store, validated at boot, none in the repo
• CORS locked to real origins, not * with credentials
• Security headers, HTTPS enforced
• Rate limits live
• Migrations run as a release step, not on app boot
• Backups enabled and one restore tested
• OpenAPI docs either public deliberately or disabled in production
• Rollback path exercised once

Failure modes

Copy-ready agent prompt

Read the skill at the URL above. Start with the Stage 1 resource table for my domain and get my approval. Then scaffold the layout, write pydantic schemas, services with the logic, routers that only delegate, one error envelope, an ownership-check dependency, cursor pagination, Alembic migrations and tests including auth failure cases. Finish with the Stage 10 deploy checklist and tell me honestly which items are not done.