An API call is a client request that invokes an operation or retrieves data. In an HTTP API, the request describes the action and required data; the server returns a response with a processing result and any resulting data. section 1.1.2
Designing an API call means mapping an operation to a path, HTTP method, input locations, response status, and output location. These choices make calls easier to use and more interoperable. section 4.1.2
Searching a product catalog
A mobile application sends GET /products?type=BD. GET represents searching, /products identifies the product catalog, and type=BD supplies a query filter. A 200 OK response returns matching products in the response body. section 4.1.1
When shaping an API call, decide:
- Which resource path represents the operation. section 4.1.2
- Which HTTP method represents the action, including verb-based operations that do not fit simple create, read, update, or delete categories. section 4.0
- Where inputs and outputs belong, and which status codes describe success or failure. section 4.1.2
- Whether repeated read or search calls retrieve data already available, so unnecessary calls can be removed from a flow. section 10.3.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-response diagram to trace how a client supplies an action and data, then receives processing status and resulting data. section 1.1.2
