Applies when designing, adding, or modifying any HTTP/REST endpoint, API resource, or web service contract. Enforces resource-oriented URLs, OpenAPI 3.1 specs, RFC 9457 problem details, pagination, idempotency, and versioning rules from Google AIP, Microsoft Azure REST Guidelines, and OpenAPI standards.
Apply these rules whenever you design, add, or modify a REST/HTTP endpoint. Treat them as hard requirements — if a request conflicts with them, surface the conflict instead of silently downgrading.
description and example on every field. Required fields are marked required: true; optional fields have explicit defaults.POST /workspaces, DELETE /workspaces/{id}, POST /workspaces/{id}:archivePOST /createWorkspace, , GET /getWorkspace?id=42POST /workspace/deleteGET (list/read), POST (create), PUT (replace), PATCH (partial update), DELETE (remove). Custom verbs use :verb suffix per Google AIP-136.camelCase. Path segments: kebab-case. Headers: kebab-case.pageSize query param + pageToken query param + nextPageToken in response (Google AIP-158), orlimit + offset query params, with a documented max limit.application/problem+json with these fields:
type — URI identifying the error classtitle — short human-readable summarystatus — HTTP status codedetail — specific instance explanationinstance — URI of the specific occurrence{"error": "message"} or {"success": false, "msg": "..."}.POST, PATCH, and DELETE endpoints that have non-idempotent side effects must accept an Idempotency-Key request header. Document the retention window for keys./v2/...) or via an api-version query/header. Never silently retype, rename, or remove fields in an existing version.200 — successful read/update with body. 201 — successful create with Location header pointing to the new resource. 204 — successful action with no body. 400 — client validation error. 401 — unauthenticated. 403 — authenticated but unauthorized. 404 — resource missing. 409 — conflict (e.g., uniqueness, version mismatch). 429 — rate-limited (with Retry-After header). 5xx — server error.If the user asks for something that violates these rules ("just return {error: ...}", "skip pagination, the list is small", "use a verb in the URL because it's clearer"), stop and explain the rule and the secure/standard alternative. Do not silently comply.