REST API Design リファレンス
リファレンス 用 REST architectural style: resources, HTTP メソッド, status codes, および best practices.
REST Constraints
REST (Representational State Transfer) is defined by six constraints: client-server, stateless, cacheable, uniform interface, layered system, and code-on-demand (optional). The uniform interface consists of resource identification, resource manipulation through representations, self-descriptive messages, and HATEOAS. Resources are identified by URIs and manipulated via HTTP methods. Statelessness requires all request context in the request itself. These constraints enable scalability and simplicity.
- stateless
- No server session
- uniform interface
- Standard HTTP methods
- HATEOAS
- Hypermedia links
all context in requestGET, POST, PUT, DELETEdiscover actionsDesign Best Practices
Use nouns for resource paths (/users, /orders/{id}), not verbs. HTTP methods map to CRUD: GET (read), POST (create), PUT/PATCH (update), DELETE (remove). Status codes indicate outcomes: 2xx success, 3xx redirect, 4xx client error, 5xx server error. Versioning via URI prefix (/v1/) or Accept header. Pagination, filtering, and sorting via query parameters. Consistent error format with machine-readable codes. Idempotency for PUT and DELETE.
- nouns not verbs
- /users not /getUsers
- methods
- GET/POST/PUT/DELETE
- versioning
- /v1/ or Accept header
resource-orientedCRUD mappingevolve safely