HTTP Range Request

Some of our API's support splitting the response body into smaller chunks. This can be especially useful for devices with a small TLS buffer. This is done using a HTTP range request as defined by RFC-7233..

This documentation is applicable for all our API's that contain an Accept-Ranges: bytes header in the response. This can be checked by executing a normal GET or HEAD request on this endpoint. It will also be explicitly stated in the API definition of that endpoint.

📘

In general, only GET endpoints can support HTTP range requests.

If the endpoint supports range requests, the client can request this using specific headers. If the request is successful and would normally return status 200 OK, it will return status 206 Partial Content instead, with only the requested byte range in the response body.

❗️

Please note that errors do not have status 200 OK, so the range request will not be applied and the response body may be larger than expected!

There are a couple of known limitations. Please check the segment “Known Limitations“ below for more info.

Headers

Request

Name

Locate

Describtion

Required

Schema

Range

request header

The range request HTTP header advertises which bytes the client wants to receive in the response body.

Default: no range request
Format: bytes=<range-start>-<range-end>
range-start: An integer indicating the beginning of the request range. The index is 0-based.
range-end: An optional integer indicating the end of the request range. The end is inclusive, so bytes=0-4 would return 5 bytes: 0, 1, 2, 3 and 4.
If omitted, the end of the response body is taken as the end of the range.

No
(Yes, for response splitting)

string

Response

Name

Location

Describtion

Required

Schema

Content-Range

response header

The Content-Range response header advertises which bytes the server has sent in the response body.

Format: bytes <range-start>-<range-end>/<size>
range-start: An integer indicating the beginning of the request range. The index is 0-based.
range-end: An integer indicating the end of the request range. The end is inclusive, so bytes 0-4/100 would return 5 bytes: 0, 1, 2, 3 and 4.
size: The total byte length of the original response.

Example: Content-Range: bytes 1024-2047/3629

Yes when status is 206;

No otherwise

string

Content-Length

response header

In the context of range requests, the Content-Length response header always reflects the actual sent response body length in bytes.

Example:
The client request Range: bytes=0-1023.
The server responds with Content-Length: 1024 and Content-Range: bytes 0-1023/3629

Yes

number

Accept-Ranges

response header

The Accept-Ranges response header advertises whether this endpoint accepts HTTP range requests. The value indicatates the supported unit to define a range.

Only the unit bytes is supported.

If the Accept-Ranges response header is present, but its value is none, range requests are not supported.

No

string

Examples

The following cURL command demonstrates how HTTP range requests could be used:

curl -i --request GET \
  --url https://device.dev.connectivity-suite.cloud/device-api/onboarding \
  --header 'Accept: application/json' \
  --header 'Range: bytes=0-1023'

This gives the following response:

HTTP/2 206
server: awselb/2.0
date: Mon, 08 Feb 2021 13:13:54 GMT
content-type: application/json; charset=utf-8
content-length: 1024
etag: W/"400-xWQvmq9+I96lV5hagdjlteB5l2o"
content-range: bytes 0-1023/3163
access-control-allow-origin: *
x-powered-by: Express

{"certificate":"-----BEGIN CERTIFICATE-----\nMIIDWjCCAkKgAwIBAgIVAOtPQsvJMiW4AZxB+JI/Y2msvE+OMA0GCSqGSIb3DQEB\nCwUAME0xSzBJBgNVBAsMQkFtYXpvbiBXZWIgU2VydmljZXMgTz1BbWF6b24uY29t\nIEluYy4gTD1TZWF0dGxlIFNUPVdhc2hpbmd0b24gQz1VUzAeFw0yMDA3MDMwNjM5\nMjJaFw00OTEyMzEyMzU5NTlaMB4xHDAaBgNVBAMME0FXUyBJb1QgQ2VydGlmaWNh\ndGUwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDkTbzZIePmMoeD1QTj\nqgV0cueKMP1jui4aKF/f46bxOYmy8rfVfbngf/xBQKLWIa3RkgPzdZCOuKLUHU6q\nAOPL102tfkr2UA4EJ7Ddi8PFQESKpyoBrX8fDeabo5iriequvKi2skAUTgr9FlPp\nMLnWNmxEfjFGR7P9jb2EPqnqSkVfC5a8oWP+Y3qS/oI717lYU7rDfR8ZGmmxp+p6\nfgR1a/Y5Zp47mWQZ4J01psMqDCA3WKh3WC5IACuACiJzBdGCJcCpRL9FWoC6YNao\nOK6YpbkhQPEgGXb7Z+JfnelKF9CQdOKrodLBi0zBRuhrxAqAINwtSU7S+LW4wnb1\nyXE/AgMBAAGjYDBeMB8GA1UdIwQYMBaAFCr/xHqxbPxhtRGXodmKCMZ5aljyMB0G\nA1UdDgQWBBQTSiQQOpoWXQ6nZgsss8i1Q/XrBDAMBgNVHRMBAf8EAjAAMA4GA1Ud\nDwEB/wQEAwIHgDANBgkqhkiG9w0BAQsFAAOCAQEAmsh6AJFKknKSFTyqcKwPErQj\nbx1XVvzwH88EINU0/2A4cjG+7jqdiNAQPksZjqvr5gQHn/tBBYOXbfndKxgqNBGk\nM9DFuYV7ABryfYb3jB0BHpw6L3NfTCtBvpXupyqHFZwEnope3ApWHwk

Errors

Malformed Range header

If the request Range header is not in the correct format, the server will respond with a 400 Bad Request status and the message “Malformed Range header“.

curl --request GET \
  --url https://device.dev.connectivity-suite.cloud/device-api/onboarding \
  --header 'Accept: application/json' \
  --header 'Range: bytes=yikes'

Response:
400 Bad Request

{
  "statusCode": 400,
  "statusText": "Bad Request",
  "errors": [
    {
      "message": "Malformed Range header: yikes"
    }
  ]
}

Unsatisfiable Range header

If both the range-start and range-end values of the request Range header are outside the available range, the server will respond with a 416 Range Not Satisfiable status and the message “Unsatisfiable Range header“.

curl --request GET \
  --url https://device.dev.connectivity-suite.cloud/device-api/onboarding \
  --header 'Accept: application/json' \
  --header 'Range: bytes=10000-10999'
Response:

Response:
416 Range Not Satisfiable

{
  "statusCode": 416,
  "statusText": "Range Not Satisfiable",
  "errors": [
    {
      "message": "Unsatistiable Range header: bytes=10000-10999"
    }
  ]
}

Known Limitations

Multipart ranges
Multipart ranges are not supported and will return the original complete response.

Conditional range requests
Conditional range requests using an If-Range header is not supported and will be ignored.

HEAD requests
Currently, HEAD requests will always have a Content-Length response header of 0, so they can not be used to retrieve the total byte length of the response beforehand.

Workaround
As a workaround, the total response byte length can be retrieved from the response Content-Range header when doing an HTTP range request. The total byte length is the value after the slash.

For example: In the response header Content-Range: bytes 0-1023/4298 the value 4298 would be the total response byte length.

References

https://developer.mozilla.org/en-US/docs/Web/HTTP/Range_requests

https://tools.ietf.org/html/rfc7233


Did this page help you?