83

What is the difference between HTTP headers Content-Range and Range? When should each be used?

I am trying to stream an audio file from a particular byte offset. Should I use Content-Range or Range header?

AmigoJack
  • 5,234
  • 1
  • 15
  • 31
lostInTransit
  • 70,519
  • 61
  • 198
  • 274

2 Answers2

139

Actually, the accepted answer is not complete. Content-Range is not only used in responses. It is also legal in requests that provide an entity body.

For example, an HTTP PUT provides an entity body, it might provide only a portion of an entity. Thus the PUT request can include a Content-Range header indicating to the server where the partial entity body should be merged into the entity.

For example, let's first create and then append to a file using HTTP:

Request 1:

PUT /file HTTP/1.1
Host: server
Content-Length: 1

a

Request 2:

PUT /file HTTP/1.1
Host: server
Content-Range: bytes 1-2/*
Content-Length: 1

a

How, let's see the file's contents...

Request 3:

GET /file HTTP/1.1
Host: server

HTTP/1.1 200 OK
Content-Length: 2

aa

This allows random file access, both READING and WRITING over HTTP. I just wanted to clarify, as I was researching the use of Content-Range in a WebDAV client I am developing, so perhaps this expanded information will prove useful to somebody else.

Hank
  • 4,597
  • 5
  • 42
  • 84
btimby
  • 1,587
  • 2
  • 10
  • 7
  • 9
    Content-Range isn't legal in requests. – Mark Nottingham Apr 20 '13 at 07:06
  • 17
    That comment is incorrect. RFC2616 (http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.16) does not limit the `Content-Range` header to requests, but binds it to a "partial entity-body". It's actually very common to use the feature to facilitate upload resume or chunked upload. – Hank Jul 12 '13 at 07:09
  • 1
    Mark's comment is correct. See: http://tools.ietf.org/html/draft-ietf-httpbis-p2-semantics-23, section 4.3.4. – grzes Sep 06 '13 at 15:39
  • 5
    I think `Content-Range` can be used in requests. See the section on PUT method: http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.6 - `The recipient of the entity MUST NOT ignore any Content-* (e.g. Content-Range) headers that it does not understand or implement and MUST return a 501 (Not Implemented) response in such cases.` - A request might contain the `Content-Range` header and the server SHOULD take it into account. – nietaki Sep 12 '13 at 21:39
  • 2
    @nietaki Sure, but that's not the same as saying it actually works as the answerer describes -- I mean, it's a guaranteed 501. – Aaron Miller Oct 04 '13 at 18:29
  • 1
    @grzes that sections says "An origin server SHOULD reject any PUT request that contains a Content-Range header field", not "MUST reject". Anyway http://lists.w3.org/Archives/Public/ietf-http-wg/2004AprJun/0033.html while old has good explanations why partial PUT is unwise. The right way to do it is PATCH but it describes what is to be patched in body, not in Content-Range headers. – Beni Cherniavsky-Paskin Dec 15 '13 at 00:51
  • Seems, like it's not possible to use PUT with Content-Range header. Is there any way to use PATCH with Content-Range? – Андрей Москвичёв Jan 07 '14 at 11:48
  • 1
    Based on my brief reading, content-range should not be used with PUT because PUT implies an idempotent operation where the entire resource is replaced. It wouldn't make sense then for a resource to be partially uploaded - which is exactly why PATCH exists. This is the current state of things anyway, I didn't look into when PATCH was available nor edits since the answer was written. – aaaaaa May 18 '16 at 06:05
  • 7
    @BeniCherniavsky-Paskin Looking at https://tools.ietf.org/html/rfc7231 rather than a draft version in section 4.3.4 I see "An origin server that allows PUT on a given target resource MUST send a 400 (Bad Request) response to a PUT request that contains a Content-Range header field (...)". Surely authors of RFCs are only humans and they do make mistakes and RFCs do evolve in pain, yet clearly the Content-Range header was not meant to be used in requests nor does it make much sense. – Hermes Nov 02 '16 at 23:22
  • 1
    Looking at https://tools.ietf.org/html/rfc7233#section-4.2 the byte range is inclusive, so request 2 should have the header `Content-Range: 1-1/*` for appending a single byte. – MT0 May 09 '17 at 10:00
  • How does this answers OP question? He is asking for the difference between the two headers. Thanks for the info anyway. – Akira Yamamoto Jul 27 '17 at 01:18
  • OneDrive uses Content-Range for requests. https://learn.microsoft.com/en-us/onedrive/developer/rest-api/api/driveitem_createuploadsession – ykaganovich Jun 08 '18 at 00:50
  • @ykaganovich Probably because the biggest disadvantage of allowing it -- proxies messing up your `PUT` requests back/forth due to ignoring `Content-*` they don't understand -- is negated by Microsoft employing exclusively their own infrastructure, which may or may not be using HTTP proxies altogether, for OneDrive, at least. Meaning they've got a single HTTP server entity that is responsible to duly respond to PUT requests with `Content-Range` headers, correctly. – Armen Michaeli Sep 14 '21 at 11:13
  • Microsoft's Graph API for Outlook also uses `Content-Range` with `PUT` for file uploads >= 3MB, see [Attach large files to Outlook messages or events](https://learn.microsoft.com/en-us/graph/outlook-large-attachments?tabs=http). – Remy Lebeau Oct 11 '21 at 19:15
89

Range is used in the request, to ask for a particular range (or ranges) of bytes. Content-Range is used in the response, to indicate which bytes the server is giving you (which may be different than the range you requested), as well as how long the entire content is (if known).

Brian Campbell
  • 322,767
  • 57
  • 360
  • 340
  • 2
    @BrunoMartinez While you can use Content-Range in the request, it was pretty clear from the question that the OP was asking about downloading content with a particular range. I was answering based on what the OP was asking, not trying to give a comprehensive description of every case in which Content-Range could be used. – Brian Campbell Dec 16 '11 at 19:45
  • 3
    @BrianCampbell you are of course correct. I just wanted to record my findings for posterity's sake. I edited my answer to make sure it does not give the impression that your answer is in any way wrong. – btimby Mar 29 '12 at 16:39
  • 3
    @btimby Not a problem! Thank you for giving a more complete explanation; it is always useful if you find the page from a Google search. – Brian Campbell Mar 29 '12 at 16:53