[ADP-140] Sunset
概述
Sunset HTTP 標頭表示資源何時將變得不可用。它幫助 API 客戶端更好地理解和管理 API 資源在開發和維護過程中的生命週期。
指導
- 針對
PARTNER_EXTERNAL或更高級別的受眾，API 應該(SHOULD)包含Sunset標頭，以促進 API 生命週期管理。- 一個日落的 API 應該(SHOULD)在其 OpenAPI 描述中包含日落資訊，僅僅指示存在 Sunset 標頭並不足以提供足夠的清晰度。
Sunset標頭應該(SHOULD)設置於臨時資源：- 例如，為臨時參考而創建的資源，預定在完成或刪除後被移除。
Sunset標頭應該(SHOULD)設置於資源保留：- 例如，因服務限制而計劃被清除的資源。
範例
臨時資源：
http
GET /jobs/{job-id} HTTP/1.1
HTTP/1.1 200 OK
Sunset: Sat, 6 Jul 2024 19:43:31 GMT
{
"jobId": "....",
"state": "SUCCESS"
}資源保留：
http
GET /reserved-seats HTTP/1.1
HTTP/1.1 200 OK
Sunset: Sat, 26 Oct 2024 19:43:31 GMTOpenAPI 範例
以下範例展示了如何在 OpenAPI 3.1.0 規範中記錄 Sunset 標頭的使用：
yaml
openapi: 3.1.0
info:
title: Example API
version: 1.0.0
components:
headers:
Sunset:
description: Indicates when the resource will be sunset
schema:
type: string
format: date-time
example: '2024-07-06T19:43:31Z'
paths:
/v1/sunset-resource:
get:
summary: API endpoint to be sunset on YYYY-MM-DD
description: This endpoint will be fully sunset on YYYY-MM-DD.
/jobs/{job-id}:
get:
summary: Get job status (temporary resource)
responses:
'200':
description: Successful response
headers:
Sunset:
$ref: #/components/headers/Sunset
content:
application/json:
schema:
type: object
properties:
jobId:
type: string
state:
type: string
/reserved-seats:
get:
summary: Get reserved seats (resource retention)
responses:
'200':
description: Successful response
headers:
Sunset:
$ref: #/components/headers/Sunset
content:
application/json:
schema:
type: object
properties:
seats:
type: array
items:
type: object
properties:
id:
type: string
status:
type: string避免重複定義已知標頭
根據 ADP-767，你應該(SHOULD)使用已經定義好的共用標頭檔案或至少使用 #/components/headers，以避免重新定義所有已知標頭。