ADP
API Design PrincipleBETA

English

繁體中文

English

繁體中文

Appearance

[ADP-125] Content-Range ​

Overview ​

The Content-Range header is a critical component in supporting partial content delivery in HTTP responses. It specifies which part of the resource is being returned in a partial response or informs the client about the total size of the resource when a range request cannot be satisfied. This functionality is particularly useful for scenarios involving large file downloads or streaming, ensuring efficient bandwidth usage and providing better control over the data transfer process.

When designing APIs that support range requests, it is essential to adhere to the specifications outlined in RFC 9110. The Content-Range header should only be used with 206 Partial Content responses, indicating successful partial content delivery, or with 416 Range Not Satisfiable responses, indicating that the requested range is invalid.

Guidance ​

  • SHOULD return Content-Range when the API is designed to support Range-Request with a successful response.

    http
    Content-Range: bytes 0-499/1234
Content-Range: bytes 500-999/1234
Content-Range: bytes 500-1233/*

  • SHOULD return Content-Range for a Range Request API when the request cannot be satisfied (as RFC 9110 suggests).

    http
    HTTP/1.1 416 Range Not Satisfiable
Content-Range: bytes */1234

  • As specified in RFC 9110, the header SHOULD only be used with 206 or 416 responses.

Implementation Details ​

Syntax ​

The Content-Range header has the following syntax:

http
Content-Range: <unit> <range-start>-<range-end>/<size>
Content-Range: <unit> <range-start>-<range-end>/*
Content-Range: <unit> */<size>
  • <unit>: The unit of measurement for the range (usually "bytes").
  • <range-start>: The start position of the range.
  • <range-end>: The end position of the range.
  • <size>: The total size of the resource, or "*" if unknown.

Usage with 206 Partial Content ​

When responding with partial content, include the Content-Range header to specify the range being sent:

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

Usage with 416 Range Not Satisfiable ​

When a range request cannot be satisfied, use the Content-Range header to inform the client about the total size of the resource:

http
HTTP/1.1 416 Range Not Satisfiable
Content-Range: bytes */146515

Best Practices ​

  1. Always include the Content-Range header in 206 and 416 responses for range requests.
  2. Ensure that the values in the Content-Range header are accurate and consistent with the actual content being sent.
  3. Handle edge cases, such as when the total size of the resource is unknown, by using "*" for the size value.
  4. Implement proper error handling for invalid range requests.
  5. Consider supporting multiple ranges in a single request, as specified in RFC 9110.

Example ​

OpenAPI 3.1.0 Example ​

yaml
openapi: 3.1.0
info:
  title: Range Request API
  version: 1.0.0
paths:
  /resource:
    get:
      summary: Get partial content
      parameters:
        - name: Range
          in: header
          required: true
          schema:
            type: string
            example: bytes=0-499
      responses:
        '206':
          description: Partial Content
          headers:
            Content-Range:
              description: Indicates the range of bytes returned
              schema:
                type: string
                example: bytes 0-499/1234
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '416':
          description: Range Not Satisfiable
          headers:
            Content-Range:
              description: Indicates the size of the full resource
              schema:
                type: string
                example: bytes */1234
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
components:
  schemas:
    Problem:
      type: object
      properties:
        type:
          type: string
          format: uri
          example: https://example.com/probs/out-of-range
        title:
          type: string
          example: Range Not Satisfiable
        status:
          type: integer
          example: 416
        detail:
          type: string
          example: The requested range is not satisfiable for the resource.
      required:
        - type
        - title
        - status

Security Considerations ​

  1. Ensure that the Content-Range header does not expose sensitive information about the resource or the system.
  2. Implement proper authentication and authorization mechanisms for range requests to prevent unauthorized access to partial content.
  3. Be cautious when supporting multiple ranges to avoid potential denial-of-service attacks.

Reference ​