An HTTP response header is a name:value metadata field returned after the status line and before the response body. It communicates protocol, representation, security, caching, or application information without placing that data in the body. section 4.6.1 section 5.1.1
Choose a response header when the output is metadata or fits a standard HTTP field; keep resource representations and error information in the body.
- Return a newly created resource’s URL in the standard Location header with a 201 Created response. section 4.6.3 section 4.9
- Avoid hiding substantial resource data in headers: product details, product lists, empty lists, and error information belong in the response body. section 4.6.3
- Prefer standard fields from the IANA HTTP Field Registry before introducing custom headers. section 4.4.1 section 4.9
Documenting a Location response header
A product-creation response can describe its required Location header in OpenAPI: responses: "201": { headers: { Location: { description: "Product URL", required: true, schema: { type: string } } } }. The header identifies the created resource, while the response body can contain the product representation. section 6.8.3 section 7.6.3
Figure 4.16 There are only two locations for data in an HTTP response: headers and body.
Use the response layout to distinguish its two data locations: headers for metadata and the body for general response data. section 4.6.1
