[ADP-135] Location

概述

Location 標頭用於 HTTP 回應中，用來將客戶端重定向到不同的 URL。它通常與 3xx (重定向) 和 201 (已創建) 狀態碼一起使用。

使用場景

Location 標頭應在以下情況下使用:

1. 提供新創建資源的 URL
2. 將客戶端重定向到不同的資源
3. 指示重定向的目標

格式

Location 標頭必須包含單一的絕對 URL。

Location: <absolute-URL>

示例

201 Created

當創建新資源時，使用 Location 標頭提供新資源的 URL:

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

301 Moved Permanently

對於永久重定向，使用 Location 標頭指定新的 URL:

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

302 Found

對於臨時重定向，使用 Location 標頭指定臨時 URL:

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

指導原則

• 使用 POST 請求創建新資源時，必須(MUST) 使用 Location 標頭指示新創建資源的 URL。
• DRAFT 在 API 版本控制場景中，應該(SHOULD)使用 Location 標頭進行重定向，以引導客戶端到新的 API 版本。
• 必須(MUST)確保 Location 標頭中的 URL 是絕對 URL，以避免任何歧義。
• 應該(SHOULD)在所有創建資源或需要重定向的 API 端點中一致地使用 Location 標頭。
• 不得(MUST NOT)在 Location 標頭 URL 中包含敏感資訊，因為它可能被中間件記錄或存儲。

OpenAPI 規範

以下是如何在 OpenAPI 中記錄 Location 標頭的示例:

openapi: 3.1.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

避免重複定義已知標頭

根據 ADP-767，你應該(SHOULD)使用已經定義好的共用標頭檔案或至少使用 #/components/headers，以避免重新定義所有已知標頭。

相關 ADPs

• ADP-110: HTTP 方法
• ADP-120: HTTP 標頭
• ADP-301: 資源導向設計
• ADP-401: API 版本控制
• ADP-767: 共用常見標頭

參考資料

• RFC 9110: Location
• MDN Web 文件: Location