Search code examples
apihttprestpaginationhateoas

Why most API paginations do not rely on HTTP Range header?


I've searched a lot but I can't find a good answer to this question. Being a HATEOAS aficionado, I would think that this header fit perfectly:

    Range: item=1-20/100

In the HTTP spec, I don't understand some "contradictions": The range unit can accept "other-range-unit"...

  range-unit       = bytes-unit | other-range-unit
  bytes-unit       = "bytes"
  other-range-unit = token

... yet the spec is later explicit:

The only range unit defined by HTTP/1.1 is "bytes". HTTP/1.1 implementations MAY ignore ranges specified using other units.

Finally the spec ends with this statement:

HTTP/1.1 has been designed to allow implementations of applications that do not depend on knowledge of ranges.

  • Is any other unit than byte allowed ?
  • If HTTP/1.1 was designed to allow app to not depend on range, what are the real drawback about relying on it for an API ?

NB: I don't care about "browsability".


Solution

  • Here the answers that I gently borrowed from this question thanks to @ptidel: Content-Range header - allowed units?.

    First, custom units are proposed in this draft HTTP/1.1, part 5: Range Requests and Partial Responses

    Second, there is a subtle difference, the first statement has been made for parsing purpose

        range-unit       = bytes-unit | other-range-unit
        bytes-unit       = "bytes"
        other-range-unit = token
    

    While the second statement has been made for producing HTTP request.

    Finally, the whole comment from Ferenc Mihaly summarizes perfectly the situation:

    I conform to the HTTP spec when I'm sending [a custom range unit] and they conform to HTTP when they ignore it

    WebDAV uses HTTP extensions correctly, IMO, but rarely works over the Internet for exactly this reason