ADP
API Design PrincipleBETA

English

繁體中文

English

繁體中文

Appearance

[ADP-140] Sunset ​

Overview ​

The Sunset HTTP header indicates when a resource will become unavailable. It helps API clients better understand and manage the lifecycle of API resources during development and maintenance.

Guidance ​

  • APIs with an audience of PARTNER_EXTERNAL or higher SHOULD include the Sunset header to facilitate API lifecycle management.
    • A sunsetting API SHOULD include sunset information in its OpenAPI description, as merely indicating the presence of a Sunset header does not provide adequate clarity.
  • The Sunset header SHOULD be set for temporary resources:
    • For example, resources created for temporary reference that are intended to be removed after completion or deletion.
  • The Sunset header SHOULD be set for resource retention:
    • For example, resources that are scheduled to be purged due to service limitations.

Examples ​

Temporary resource:

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"
}

Resource retention:

http
GET /reserved-seats HTTP/1.1

HTTP/1.1 200 OK
Sunset: Sat, 26 Oct 2024 19:43:31 GMT

OpenAPI Example ​

The following example demonstrates how to document the use of the Sunset header in an OpenAPI 3.1.0 specification:

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

Refrain from redefining known headers

As per ADP-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.

Reference ​