REST is an architectural style for distributed systems. It separates clients and servers, keeps interactions stateless, supports caching and layering, and uses a uniform interface built around resource representations, standard methods, and metadata. These constraints aim to make networked systems efficient, scalable, reliable, simple, portable, and modifiable. section 4.8.1
A REST API uses HTTP extensively and respects its semantics rather than treating HTTP merely as a transport channel. Clients send requests containing the action and required data; servers return status and resulting data while concealing implementation details. section 3.1.2 section 3.1.3
Designing a REST programming interface typically proceeds by:
- Identifying business concepts as resources and mapping their relationships. section 3.0
- Representing actions with resource paths and standard HTTP methods, such as GET for searching and POST for creating or sending. section 3.1.4
- Using HTTP status codes for success and failure, then modeling request and response data with named, typed objects or arrays. section 3.1.4
Searching products
A mobile application or command-line client can send GET /products. The server may return 200 OK with a product list, regardless of how products are stored. A REST-oriented deletion instead uses DELETE /products/123 and returns 404 Not Found when that product does not exist, rather than using GET /deleteProduct/123 with a misleading success response. section 3.1.2 section 3.1.3
Figure 1.2 When calling a web API, the consumer sends an HTTP request indicating what to do and the needed data. Once the request is processed, the server returns an HTTP response indicating how the processing went and the resulting data.
Use the request-and-response diagram to trace how a consumer expresses an operation and receives processing status and resulting data. section 1.1.2
REST is a useful default, not a universal answer. Consider streaming, bidirectional communication, event delivery, or backend-for-frontend requirements carefully; SSE, WebSockets, event-driven architecture, or GraphQL may fit those contexts better. Avoid sterile arguments about singular or plural paths: naming conventions do not determine RESTfulness. section 14.8.2 section 4.8.3
