ADP
API Design PrincipleBETA

English

繁體中文

English

繁體中文

Appearance

[ADP-351] Range Request ​

reviewing phase 1

Isolate Accept-Range to a new ADP

Overview ​

Range Requests allow clients to request partial content from a server, which is particularly useful for large resources or resumable downloads.

Guidance ​

  • Servers SHOULD respond with the Accept-Ranges header to inform the client that Range Requests are supported, regardless of whether the client's request includes any Range Request related headers.

    http
    HTTP/1.1 200 OK
Accept-Ranges: bytes

  • Servers MAY send Accept-Ranges: none to explicitly indicate that Range Requests are not supported for the requested resource.

  • Servers SHOULD honor the Range header in requests and return partial responses when supported.

    • Responses SHOULD have an HTTP status of 206 Partial Content in this case.

    • Responses SHOULD include the Content-Range header to indicate which ranges are being returned.

    • Responses SHOULD include the Accept-Ranges header in this case.

      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

  • Servers SHOULD respond with HTTP status 416 (Range Not Satisfiable) if the requested Range is not satisfiable or the unit is not supported. See HTTP Headers - Range for more details.

  • DRAFT Servers SHOULD support the If-Range header, which allows clients to make a conditional request for a range. If the entity has not changed since the specified date or ETag, the server should return the requested range. If it has changed, the server should return the entire resource with a 200 OK status.

    http
    GET /resources/r-id HTTP/1.1
If-Range: "etag-value"  // or a date

HTTP/1.1 206 Partial Content
Content-Range: bytes 0-1023/146515
Content-Length: 1024
Accept-Ranges: bytes

Documentation ​

  • Clearly document the support for Range Requests in API specifications.
  • Include examples of valid Range Request syntax in API documentation.
  • Document any limitations or special considerations for Range Requests in your API.

References ​

Changelog ​

  • 2024.10.01 Add If-Range