GET is the HTTP method for reading or retrieving a resource without requesting a state-changing action. A client identifies the resource with a path, and the server returns a representation with an HTTP status and response body. section 3.1.1 section 4.3.1
Searching a product catalog
A mobile application can send GET /products?type=BD to search the product catalog. The query parameter supplies a filter, while a 200 OK response returns the matching products in the response body. section 4.1.1 section 4.1.2
Use GET consistently for read-oriented operations:
- List or search a collection with GET /elements. section 4.3.6
- Read one resource with GET /elements/{element identifier}. section 4.3.6
- Place filters in query parameters, such as ?type=BD, rather than encoding them as an action path. section 4.1.1 section 9.3.1
- Do not use GET to modify or delete data; respect its safe, read-only semantics. section 9.3.1 section 12.5.2
- Rely on standard paths and statuses so consumers can predict behavior, such as 404 Not Found for a missing resource. section 9.1.3
Figure 4.3 The mobile application searches the catalog for BD products. The API server returns the products with type BD.
The catalog-search diagram connects the GET method, collection path, query filter, and returned product list in one API interaction. section 4.1.1
