ADE
API Design EssentialsBETA

English

繁體中文

English

繁體中文

Appearance

[ADE-135] Location ​

Overview ​

The Location header is used in HTTP responses to redirect the client to a different URL. It is commonly used with 3xx (Redirection) and 201 (Created) status codes.

Usage ​

The Location header should be used in the following scenarios:

  1. To provide the URL of a newly created resource
  2. To redirect the client to a different resource
  3. To indicate the target of a redirection

Format ​

The Location header MUST contain a single absolute URL.

http
Location: <absolute-URL>

Examples ​

201 Created ​

When a new resource is created, use the Location header to provide the URL of the new resource:

http
HTTP/1.1 201 Created
Location: https://api.example.com/users/123

301 Moved Permanently ​

For permanent redirects, use the Location header to specify the new URL:

http
HTTP/1.1 301 Moved Permanently
Location: https://api.example.com/v2/resources

302 Found ​

For temporary redirects, use the Location header to specify the temporary URL:

http
HTTP/1.1 302 Found
Location: https://api.example.com/temporary-page

Guidance ​

  • MUST use the Location header when creating new resources with POST requests to indicate the URL of the newly created resource.
  • DRAFT SHOULD use the Location header for redirects in API versioning scenarios to guide clients to the new API version.
  • MUST ensure that the URL in the Location header is an absolute URL to avoid any ambiguity.
  • SHOULD use the Location header consistently across all API endpoints that create resources or require redirects.
  • MUST NOT include sensitive information in the Location header URL as it may be logged or stored by intermediaries.

OpenAPI Specification ​

Here's an example of how to document the Location header in OpenAPI:

yaml
openapi: 3.0.0
info:
  title: Example API
  version: 1.0.0
paths:
  /resources:
    post:
      summary: Create a new resource
      responses:
        '201':
          description: Resource created successfully
          headers:
            Location:
              schema:
                type: string
              description: URL of the newly created resource

Refrain from redefining known headers

As per ADE-767, you SHOULD utilize the external headers definition YAML or reference #/components/headers using $refs, thereby avoiding the redefinition of known headers across all operations.

References ​