# Auditing API Contracts

> Analyzes Express route definitions and controller logic to document API endpoints, payloads, and response structures. Use when reverse-engineering an existing Express application's API surface.

- Skill: `googlecloudplatform/auditing-api-contracts` (Agent Skill)
- Install (CLI): `npx skillmds@latest add googlecloudplatform/auditing-api-contracts`
- Raw SKILL.md: https://api.skillmd.com/api/skills/googlecloudplatform/auditing-api-contracts/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: GoogleCloudPlatform (https://skillmd.com/u/googlecloudplatform)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/googlecloudplatform/auditing-api-contracts

---


# Auditing API Contracts

Analyze the surface area of a legacy application's API to precisely document its behavior for recreation in a modern framework (e.g., Next.js Route Handlers).

## Objective
Reverse-engineer the legacy API's routes, payloads, and response structures, categorizing them by **Primary Resources** and **Sub-resources**.

## Instructions for the Audit Subagent

Copy this checklist and track your progress:
```
Task Progress:
- [ ] Step 1: Locate the Routes & Controllers
- [ ] Step 2: Categorize Resources
- [ ] Step 3: Identify Common Patterns
- [ ] Step 4: Analyze Each Endpoint
- [ ] Step 5: Generate API_Contracts.md
```

### Step 1. Locate the Routes & Controllers
Search the legacy codebase (e.g., `../ExpressModernization-Old/`) for where endpoints are defined (usually `config/routes.js`, `routes/`, or directly in `app.js`/`server.js`). Trace each route to its corresponding controller function.

### Step 2. Categorize Resources
Divide the API surface into:
- **Primary Resources**: High-level entities (e.g., `Users`, `Products`, `Posts`).
- **Sub-resources**: Dependent entities linked to a primary resource (e.g., `Comments` belonging to a `Post`, `Reviews` for a `Product`).

### Step 3. Identify Common Patterns
Look for a **Common Response Envelope**. Is the API consistent in how it returns data?
- *Example 1 (Wrapped):* `{ success: true, data: [...], meta: { total: 100 } }`
- *Example 2 (Unwrapped):* Returns the object/array directly.
Identify common status codes for success, validation failure (400/422), and authorization failure (401/403).

### Step 4. Analyze Each Endpoint
For every endpoint, document:
- **Method & Path**: e.g., `GET /resource/:id/sub-resource`
- **Middleware Analysis**: List middleware functions (e.g., `requiresLogin`, `hasAuthorization`). Document what they implicitly check (Session, Ownership, Roles).
- **Inbound Data**: Examine `req.body`, `req.query`, and `req.params`. Identify required vs. optional fields and their data types.
- **Outbound Structure**: Document the exact shape of the returned JSON or the redirect target.
- **Error States**: How does the controller handle failures (Mongoose errors, empty results, invalid IDs)?

### Step 5. Generate API_Contracts.md & Identify Probes
Compile findings into a single, highly detailed artifact at `docs/legacy-audit/API_Contracts.md`. 
**Critical:** Ensure that all of the endpoints are listed in a **checklist** within the artifact. The agent will use this checklist during the later scaffolding phase of the modernization workflow to ensure nothing is missed. Also, identify any necessary route redirects (e.g., `/articles` -> `/` if an endpoint isn't actually implemented but routing behavior is expected).
Additionally, **identify specific parity probes** (e.g., "The search API must be queried with an empty string to ensure it returns the same default sort as legacy"). **Append** these specific test cases to `docs/verification/Verification_Plan.md`.