rest-api-architectlisted

# REST API Architecture Cross-language conventions for HTTP/JSON REST APIs. Framework-agnostic. Pair with [fastapi-architect](../../frameworks/fastapi-architect/SKILL.md) or [gin-architect](../../frameworks/gin-architect/SKILL.md) for implementation. See [STACK.md](STACK.md) for the specs this skill is built on. ## 1. URL & resource design - **Plural nouns for collections:** `/v1/users`, `/v1/orders`. Never verbs in URLs (`/v1/createUser` is wrong — the method is the verb). - **Resource ID in the path:** `/v1/users/{user_id}`, never as a query parameter. - **Nest only one level deep** for true containment: `/v1/orders/{order_id}/items`. Beyond one level, use IDs and filter queries instead — deeper hierarchies turn brittle the moment relationships change. - **`snake_case` in URLs and query params.** Consistent with the JSON casing below. - **Sub-resources expose hierarchy, not actions.** `/v1/orders/{id}/cancellation` (PUT to create) instead of `POST /v1/orders/{id}/cancel`. The state change is *what is created*, not a verb on the parent. ## 2. HTTP method semantics | Method | Purpose | Idempotent | Safe | |---|---|---|---| | `GET` | Read | Yes | Yes (no side effects) | | `POST` | Create (server assigns ID) **or** action that doesn't fit elsewhere | **No** | No | | `PUT` | Replace entire resource (client supplies full state) | Yes | No | | `PATCH` | Partial update | **No** (unless body is itself idempotent — usually not) | No | | `DELETE` | Remove | Yes | No | - **`PUT`