api-conventionslisted

## URL Design - Use kebab-case for URL path segments: `/user-profiles`, not `/userProfiles` or `/user_profiles` - Use plural nouns for resource collections: `/orders`, `/products`, `/users` - Nest resources at most one level deep: `/orders/{id}/items` is fine; `/orders/{id}/items/{id}/notes` is too deep - promote `notes` to a top-level resource - Never use verbs in URLs. The HTTP method is the verb: `DELETE /sessions/{id}` not `POST /logout` - Resource IDs go in the path; filters go in query params: `GET /products?category=books&min_price=10` ## HTTP Methods | Method | Semantics | Idempotent | Safe | |--------|-----------|------------|------| | GET | Read resource(s) | Yes | Yes | | POST | Create resource or trigger action | No | No | | PUT | Replace resource entirely | Yes | No | | PATCH | Partial update | No | No | | DELETE | Remove resource | Yes | No | - Use `POST /resources` to create. Return `201 Created` with `Location` header pointing to the new resource. - Use `PATCH` for partial updates, not `PUT`, unless clients always send the full representation. ## Response Format All responses use JSON. Property names use camelCase: ```json { "id": "ord_01HXZ", "userId": "usr_abc", "status": "pending", "createdAt": "2025-03-15T10:00:00Z", "items": [ { "productId": "prd_xyz", "quantity": 2, "unitPrice": 9.99 } ] } ``` - Dates and times are ISO 8601 in UTC: `"2025-03-15T10:00:00Z"` - IDs are strings (never expose raw database integer IDs) - Monetary amount