Backend APIs: HTTP Service Design and Implementation

Design and review HTTP APIs that stay coherent as they grow. Focus on contracts, auth boundaries, error models, and framework structure for Python and Node.js services.

Target versions (May 2026):

• FastAPI 0.135.3 (released 2026-04-01)
• Express 5.2.1 (published 2025-12-01)
• NestJS 11.1.18 (published 2026-04-03)
• OpenAPI Specification 3.2.0 (published 2025-09-19)
• HTTP Semantics: RFC 9110 (June 2022)
• Problem Details for HTTP APIs: RFC 9457 (July 2023)
• OAuth 2.0 Security Best Current Practice: RFC 9700 (January 2025)

This skill works across five concerns:

• Contract design - resources, methods, status codes, schemas, versioning
• API ergonomics - pagination, filtering, sorting, idempotency, error format
• Framework structure - FastAPI dependencies, Express middleware, NestJS modules and guards
• Authentication - sessions, bearer tokens, OAuth/OIDC, BFF and token mediation
• Review - unstable contracts, DTO leakage, auth confusion, and HTTP misuse

When to use

• Designing a new REST or HTTP API
• Reviewing an existing FastAPI, Express, or NestJS service
• Writing or fixing OpenAPI specifications and generated docs
• Choosing status codes, error formats, pagination, filtering, or versioning strategy
• Designing auth flows for browser, mobile, machine-to-machine, or third-party clients
• Refactoring route or controller structure that has become hard to reason about
• Planning backward-compatible API evolution
• Defining idempotency and retry behavior for write endpoints

When NOT to use

• GraphQL schema, resolvers, federation, or persisted query work - out of scope for this skill
• gRPC, protobuf schema evolution, or streaming RPCs - out of scope for this skill
• Database schema, indexing, replication, or query tuning - use databases
• General bug-finding, race-condition hunting, or correctness review outside the API boundary - use code-review
• Security auditing for auth bypasses, injection, secrets, or OWASP findings - use security-audit
• Writing or debugging automated tests - use testing
• Deployment, containers, gateways, ingress, or cluster config - use docker, kubernetes, or networking
• CI/CD pipeline design for API delivery - use ci-cd
• MCP-specific HTTP servers and tool handlers - use mcp

AI Self-Check

Before returning API code, route design, or OpenAPI output, verify:

• Resource names are nouns and URL shape is stable (/users/{userId}/sessions, not /doUserSessionThing)
• Method semantics follow RFC 9110 - no "GET that mutates", no PATCH used as a vague catch-all
• 401 vs 403 is correct: unauthenticated vs authenticated-but-forbidden
• Ownership-hiding behavior is deliberate and consistent: decide when out-of-scope resources return 404 vs 403
• Error responses use one consistent format, preferably RFC 9457 problem details
• Request and response DTOs are explicit and separate from ORM or database models
• Input validation happens server-side even if clients or SDKs also validate
• Offset pagination is not used blindly on large or high-churn collections where cursor pagination is the safer default
• Write endpoints that may be retried (POST /payments, webhook receivers, order creation) define idempotency behavior
• OpenAPI docs match real handler behavior, examples, status codes, and auth requirements
• First-party browser apps do not get long-lived bearer tokens stored in browser storage by default
• Cookie-based browser auth accounts for cookie scope and CSRF behavior instead of assuming cookies are automatically safe
• OAuth guidance is current: authorization code + PKCE, no implicit flow, no resource owner password credentials
• Sensitive defaults are explicit: cookie flags, token TTLs, scope boundaries, and rate limits are not hand-waved
• Current source checked: dated versions, CLI flags, API names, and support windows are verified against primary docs before repeating them
• Hidden state identified: local config, credentials, caches, contexts, branches, cluster targets, or previous runs are made explicit before acting
• Verification is real: final checks exercise the actual runtime, parser, service, or integration point instead of only linting prose or happy paths
• Routing overlap checked: overlapping skills, trigger terms, and "When NOT to use" boundaries are checked before returning guidance
• Spec claims verified: claims about tool behavior, output contracts, or repo conventions are checked against current docs, scripts, or skill files
• Framework version checked: FastAPI, Express, NestJS, and OpenAPI examples match current APIs and migration notes
• Contract compatibility checked: response codes, pagination, errors, and auth behavior preserve existing clients unless a version bump is explicit
• Injection in handler body flagged as contract defect: if injection (SQL, command, header, path traversal) is found inside a route handler, flag it as a missing validation-boundary defect at the contract layer and recommend fixing it there; route to security-audit for a full injection audit if the pattern is widespread

Performance

• Paginate and filter at the data store; never load full collections just to slice in the handler.
• Set timeouts and body limits at the framework, proxy, and client layers.
• Measure p95/p99 latency and error rates for changed endpoints before optimizing internals.

Best Practices

• Design idempotency for retries on create, payment, provisioning, and webhook endpoints.
• Generate or validate OpenAPI from the implementation contract and keep examples executable.
• Use explicit auth scopes and tenancy checks in handlers, not only in route grouping or UI state.

Workflow

Build vs. Review: when reviewing an existing service, still walk the same steps. Determine the API boundary, audit the contract, trace auth, then compare the implementation against the published behavior instead of jumping straight into handler code.

Step 1: Determine the boundary

Clarify the API before picking framework patterns:

• Who calls it? Browser app, mobile app, third-party integrator, internal service, webhook sender
• What kind of API is it? Public API, private app backend, internal service, admin API
• Is the task greenfield or review? New design, incremental change, migration, or bug fix
• What stability promise exists? Internal-only, versioned public API, or "best effort"
• What auth model already exists? Session cookies, JWT bearer, API keys, OAuth/OIDC, or none yet
• What house style already exists? Error format, pagination shape, versioning scheme, auth boundary, DTO naming

If the user asks to "just add an endpoint", inspect the surrounding service first. Most bad API work happens when one route lands with a different error model, auth rule, pagination shape, or DTO style than the rest of the service.

Step 2: Choose the framework pattern

Pick the framework that matches the codebase and team constraints. Do not switch frameworks for fashion.

Framework rules:

• FastAPI - keep dependencies explicit, use response models, and centr