The Prefer header lets an HTTP client express processing preferences without changing the resource’s usual media type. It can help consumers request less or more data, choose returned representations, or select an execution mode. section 13.5.1 section 14.7.4
For model selection, define a preference such as Prefer: model=summarized or Prefer: model=complete. The response can keep Content-Type: application/json and identify the chosen model with Preference-Applied. If no preference is supplied, the operation uses its default model. section 13.5.1
Choosing response size
GET /accounts with Prefer: model=complete requests complete account representations instead of the usual summary. For creation, POST /account-applications with Prefer: model=none returns 201 Created and a Location header without resource data; model=summarized or model=minimal can request a smaller response instead. section 13.5.1 section 13.5.2
Choosing execution mode
POST /simulations with Prefer: response=synchronous waits for completion and returns 201 Created with DONE. Omitting the preference or using response=asynchronous returns 202 Accepted with IN_PROGRESS. Restrict synchronous execution to consumers with the simulation:run:synchronous scope when needed. section 14.7.4
Figure 13.9 We can use a custom media type or preference to get the complete or summarized model on any read, list, or search operation.
Compare custom media types with Prefer-based model selection across read, list, and search operations. section 13.5.1
Prefer-based choices are useful but uncommon, so document their values and defaults clearly. Use them cautiously: synchronous long-running requests can strain infrastructure, exhaust connections, or fail through timeouts. section 13.5.1 section 14.7.4
