review-api-contract

Review: API Contract

Overview

This skill defines the review process for REST API changes — new endpoints, modified response shapes, versioning decisions, and breaking change assessment. Use it alongside review-code-quality-process when a PR exposes or modifies an HTTP API surface. Where code quality questions arise (auth middleware, error handling, testing), defer to that skill; this one focuses on the contract itself.

When to Use

• Reviewing a PR that adds, modifies, or removes API endpoints
• Evaluating a proposed API design before implementation begins
• Assessing whether a change is breaking before it ships
• Auditing an existing API for consistency and correctness

---

Dimension 1: Resource Naming

Goal: Verify that endpoint paths follow REST conventions and are consistent with existing routes.

Questions:

• Are resources named with nouns, not verbs? (/users not /getUsers)
• Are collection names plural? (/orders not /order)
• Are nested resources used only for genuine ownership relationships? (/users/{id}/orders)
• Are path parameters meaningful and stable identifiers? (prefer userId over positional index)
• Is casing consistent across all routes? (kebab-case preferred: /payment-methods)
• Are query parameters used for filtering, sorting, and field selection rather than resource identity?

Red flags:

• /createOrder, /deleteUser, /fetchPayments — verbs in paths
• /user for a collection endpoint — missing plural
• /users/{userId}/addresses/{addressId}/lines/{lineId} — nesting beyond two levels
• Mixing /userId and /user_id across routes

Severity: MEDIUM for naming inconsistency; HIGH if a new naming pattern is established that conflicts with existing routes (causes confusion for API consumers).

---

Dimension 2: HTTP Methods and Semantics

Goal: Confirm each method is used according to its HTTP semantics.

Questions:

• Does GET only read? No state changes triggered by a GET request?
• Does POST create a new resource or trigger a non-idempotent action?
• Is PUT used for full replacement and PATCH for partial update?
• Does DELETE remove without requiring a request body?
• Are safe methods (GET, HEAD, OPTIONS) free of side effects?