Operation output is the information an API operation returns in its result. HTTP represents it through response status codes and locations such as response bodies or headers; a successful search might return product information in the body with 200 OK. section 4.1.2 section 4.6
Figure 4.4 We focus on paths, HTTP methods, HTTP statuses, and the locations of input and output data in HTTP requests and responses.
Use this overview to connect an operation’s path and method with its response status, output location, and returned data. section 4.1.2
Design output by deciding what consumers need and where each part belongs:
- Return the created resource representation or a minimal reference after creation. A 201 Created response must include the created resource URL in a Location header, even when no body is returned. section 4.6.2
- Return updated data when choosing 200 OK for a modification; choose 204 No Content when the response intentionally has no body. section 4.6.2
- Represent empty successful results explicitly, such as an empty products list, and return error information in error responses because status codes alone may be insufficient. section 4.6.2
- Keep filters aligned with returned properties so consumers can infer available filters and understand the data they retrieve. section 9.6.1
Describe output in OpenAPI after choosing its HTTP location. Define response bodies, bodyless responses, and response headers there; use JSON Schema for both body data and non-body data, while keeping their OpenAPI locations distinct. section 6.8 section 7.5
A consumer-focused search response
A transaction search can accept date, category, and amount filters and return matching transactions with those same properties. A consumer can therefore request GET /accounts/12345/transactions?date=2024-03-06&category=restaurant&amount=100 and understand how the filters relate to the result. section 9.6.1
Treat output as a compatibility contract. Do not remove expected properties, make required data optional, rename fields, change types or formats, or replace known enumeration values unexpectedly. Adding data within the original limits is generally compatible because unchanged consumers can ignore it. section 15.2.1
