[ADP-127] Deprecation

指導原則

• 當資源或 API 有新版本時，你應該(SHOULD)使用 Deprecation 標頭告知棄用日期，並使用 Link 標頭來通知客戶端替代方案，使用已註冊的關係類型 alternate。值類型應(SHOULD)為結構化過濾日期，定義見 https://datatracker.ietf.org/doc/draft-ietf-httpbis-sfbis/

  GET /v1/resources HTTP/1.1
  
  HTTP/1.1 200 OK
  Deprecation: @123456789
  Link: </v2/resources>; rel="alternate",
        <https://dev.doc/deprecation-policy>; rel="deprecation"

• 你可以(MAY)提供一個關係類型為 deprecation 的連結，以告知客戶端在哪裡可以找到棄用資訊。

  Link: <https://developer.example.com/deprecation>;
           rel="deprecation"; type="text/html"

示例

OpenAPI 示例

openapi: 3.1.0
info:
  title: Example API
  version: 1.0.0
paths:
  /v1/resources:
    get:
      summary: Get resources (deprecated)
      deprecated: true
      responses:
        '200':
          description: Successful response
          headers:
            Deprecation:
              description: Indicates that the API version is deprecated
              schema:
                type: string
                example: '@123456789'
            Link:
              description: Provides links to the new version and deprecation policy
              schema:
                type: string
                example: '</v2/resources>; rel="alternate"， <https://dev.doc/deprecation-policy>; rel="deprecation"'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        value:
                          type: string
  /v2/resources:
    get:
      summary: Get resources (new version)
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        value:
                          type: string

關聯 ADPs

• ADP-42: API 生命週期

參考資料

• https://datatracker.ietf.org/doc/html/draft-ietf-httpapi-deprecation-header

  注意：這仍是草案，可能會在之後發生變化。

• https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel