The Location header identifies a URI associated with an HTTP response. For a successful resource creation, it points to the new resource so consumers can retrieve it later, even when the response contains little or no data. section 4.6.2 section 4.6.4
Creating a catalog product
A POST /products response can use 201 Created, return product data, and include Location: /products/12345. A consumer can then send GET /products/12345. If only minimal product information is returned, the header still supplies the retrieval URL. section 4.6.2 section 5.3.3
Use the header according to the operation and response flow:
- Return the created resource’s URL in Location for successful POST or PUT creation responses. section 4.6.4
- Use 303 See Other with Location when a consumer should retrieve a finalized resource elsewhere; the response has no body. section 10.4.7
- Use 202 Accepted with Location to identify a status resource that consumers can poll during a long-running operation. section 14.7.1
- Consider element-specific Location headers when bulk operations create multiple resources and require per-element status information. section 13.7.5
Describing Location in OpenAPI
Define the header in the 201 Response object’s headers map. Mark it required when it is always returned, describe it as the product URL, and use an inline string schema for its value. section 6.8.3 section 7.6.3
Listing 6.12 Response header
...
paths:
/products:
summary: Catalog
...
post:
summary: Add a product to the catalog
...
responses:
"201":
description: Product added to the catalog
headers: #1
Location: #2
description: Product URL #3
required: true #4
schema: {} #5
content: ...
Inspect the concrete OpenAPI response-header definition for POST /products. section 6.8.3
