design_api_contractslisted

# design_api_contracts An API is a contract. Once clients start depending on it, changing it breaks them. Design APIs as if you'll never be able to change them — because in practice, change is expensive. ## REST API Design Principles ### Resources and URLs URLs identify resources (nouns), not actions (verbs). HTTP methods are the verbs. ``` Good Bad GET /orders GET /getOrders POST /orders POST /createOrder GET /orders/123 GET /getOrder?id=123 PUT /orders/123 POST /updateOrder/123 DELETE /orders/123 POST /deleteOrder PATCH /orders/123 PUT /orders/123/partialUpdate GET /orders/123/items GET /getItemsForOrder?orderId=123 POST /orders/123/cancel POST /cancelOrder ← OK for actions that aren't CRUD ``` **Resource naming:** - Plural nouns: `/orders`, `/users`, `/products` - Hierarchical for nested resources: `/users/123/orders` - Use actions as sub-resources for operations that don't map to CRUD: `/orders/123/cancel`, `/invoices/456/send` ### HTTP Methods | Method | Meaning | Idempotent? | Body? | |---|---|---|---| | GET | Retrieve | Yes | No | | POST | Create | No | Yes | | PUT | Replace entirely | Yes | Yes | | PATCH | Partial update | No (usually) | Yes | | DELETE | Remove | Yes | No | **Idempotent**: calling it multiple times has the same effect as calling it once. GET and DELETE should always be idempotent. PUT should be idempotent (sending the same body twice le