api-audit

Overview

API audit pipeline: discovery → endpoint inventory → naming audit → response audit → validation audit → auth audit → scorecard. Read-only analysis that produces a prioritized report.

Required References

Before starting, read references/backend/api-design.md for REST conventions, naming rules, and response format standards.

Step 1: Discovery

1. Framework detection:
   • package.json with fastify/express/hapi/koa → Node.js
   • pyproject.toml with fastapi/django/flask → Python
   • app/api/ or pages/api/ directory → Next.js API routes
2. Route file inventory:
   • Fastify: glob for *.routes.ts, *.controller.ts, files with fastify.get/post/put/delete
   • Express: files with router.get/post/put/delete or app.get/post/put/delete
   • FastAPI: files with @router.get/post/put/delete or @app.get/post/put/delete
   • Next.js: app/api/**/route.ts or pages/api/**/*.ts
3. Auth infrastructure:
   • Grep for auth middleware, guards, decorators (authenticate, requireAuth, Depends, preHandler)
   • Identify auth strategies (JWT, API key, session, OAuth)

Step 2: Endpoint Inventory

For each endpoint, extract:

Field	Source
Method	GET/POST/PATCH/PUT/DELETE
Path	Route path with parameters
Handler	Function name and file location
Auth	Required/optional/none
Validation	Input schema (Zod/Joi/Pydantic) or none
Response type	Typed response or untyped

Build complete inventory table.

Step 3: Naming Audit

Check each endpoint against REST conventions:

1. Resource naming:
   • Nouns, not verbs (/users not /getUsers)
   • Plural collection names (/users not /user)
   • Lowercase with hyphens (/user-profiles not /userProfiles)
2. Method-path alignment:
   • GET for reads, POST for creates, PATCH for updates, DELETE for deletes
   • No POST /deleteUser or GET /createItem
3. Path parameter naming:
   • Consistent ID parameter naming (:id vs :userId vs :user_id)
   • Nested resources use parent path (/users/:id/posts not /user-posts/:userId)
4. Versioning:
   • Consistent versioning strategy (path prefix /v1/ or header)