Skip to content
ADP
API Design PrincipleBETA

[ADP-351] 範圍請求

reviewing phase 1

將 Accept-Ranges 獨立

概述

範圍請求允許客戶端向伺服器請求部分內容,這對於大型資源或可恢復的下載特別有用。

指導原則

  • 伺服器應該(SHOULD)回應 Accept-Ranges 標頭,以告知客戶端支援範圍請求,無論客戶端的請求是否包含任何與範圍請求相關的標頭。

    http
    HTTP/1.1 200 OK
    Accept-Ranges: bytes
  • 伺服器可以(MAY)發送 Accept-Ranges: none 以明確表示不支援所請求資源的範圍請求。

  • 伺服器應該(SHOULD)在支援時遵守請求中的 Range 標頭並返回部分回應。

    • 在這種情況下,回應應該(SHOULD)有 206 Partial Content 的 HTTP 狀態。

    • 回應應該(SHOULD)包含 Content-Range 標頭,以指示正在返回哪些範圍。

    • 在這種情況下,回應應該(SHOULD)包含 Accept-Ranges 標頭。

      http
      GET /resources/r-id HTTP/1.1
      Range: bytes=0-1023
      
      HTTP/1.1 206 Partial Content
      Content-Range: bytes 0-1023/146515
      Content-Length: 1024
      Accept-Ranges: bytes
  • DRAFT 伺服器應該支持 If-Range 標頭,這允許客戶端對範圍進行條件請求。如果實體自指定日期或ETag以來未改變,伺服器應該返回請求的範圍。如果它已經改變,伺服器應該返回整個資源,狀態為200 OK。

    http
    GET /resources/r-id HTTP/1.1
    If-Range: "etag-value"  // 或日期
    
    HTTP/1.1 206 Partial Content
    Content-Range: bytes 0-1023/146515
    Content-Length: 1024
    Accept-Ranges: bytes
  • 如果請求的範圍不可滿足或不支援該單位,伺服器應該回應 HTTP 狀態 416 (Range Not Satisfiable)。有關更多詳細資訊,請參閱 HTTP 標頭 - Range

文件

  • 在 API 規範中清楚地記錄對範圍請求的支持。
  • 在 API 文件中包含有效範圍請求語法的示例。
  • 記錄 API 中範圍請求的任何限制或特殊考慮事項。

關聯 ADPs

參考

Changelog

  • 2024.10.01 Add If-Range