RESTful API Contract Template for PMs

Use PATCH for partial updates (send only the fields you want to change). Use PUT for full replacements (send the complete resource, overwriting everything). Most modern APIs use PATCH because partial updates are more common and more bandwidth-efficient. If you support PUT, require the client to send every field. If a field is omitted in a PUT, treat it as explicitly set to null or the default value.

Nest resources one level deep when there is a strong parent-child relationship: `/projects/:id/tasks`. Avoid nesting deeper than two levels (`/projects/:id/tasks/:id/comments`) because it creates long URLs and forces clients to know the full hierarchy. Instead, promote deeply nested resources to top-level: `GET /comments?task_id=123`. This is simpler and supports use cases like "get all comments by a user" that do not fit the parent-child URL structure.

Pick one and be consistent across the entire API. `snake_case` is the convention for APIs built with Python, Ruby, and Go. `camelCase` is the convention for JavaScript-ecosystem APIs. If your primary consumers are JavaScript/TypeScript frontends, `camelCase` reduces the need for client-side field mapping. This template uses `snake_case` because it is the more common choice in public APIs (Stripe, GitHub, Twilio all use it).

Use URL path versioning (`/v1/`). When a breaking change is necessary, create `/v2/` endpoints and keep `/v1/` running during the deprecation period. Add a `Sunset` header to v1 responses with the removal date. Monitor v1 usage in your analytics to know when it is safe to decommission. Non-breaking changes (new optional fields, new endpoints) ship within the current version. See the [API Design Specification Template](/templates/api-design-spec-template) for detailed versioning rules.

400 (Bad Request) means the request is syntactically invalid: malformed JSON, wrong content type, or missing required fields. 422 (Unprocessable Entity) means the request is syntactically valid but fails business rules: a start date after an end date, a transfer amount exceeding available inventory, or a status transition that is not allowed. Some teams use 400 for both. The distinction is useful when consumers need to differentiate between "fix your request format" and "fix your business logic." ---