Using HTTP status code 206 - Partial Content for pagination

user_4834383 0
Viewed 315

Background

Our team has brought up the idea of using status code 206 - Partial Content in our REST API to indicate that GET requests over large datasets have more content than was returned, in order to allow the API user to paginate. This would be an alternative to the hasMore flag we are currently use in the response body.

Pro

  • Using a known status code would allow users of the API to rely on common HTTP language instead of learning our 'proprietary' language.
  • The claim that it would be very fitting to signal whether or not there are more results.

Con

  • Since all requests have a pageSize numeric query parameter, it might be incorrect to communicate 206 - Partial Content since the response contains all the results that were requested by the pageSize query param.
  • The claim that 206 - Partial Content is commonly used for byte streams, not for lists of collections.

Question

In which cases could or should 206 - Partial Content be used for pagination of results sets sent in response to restful GET requests?

rest pagination http
1 Answers

Our team has brought up the idea of using status code 206 - Partial Content in our REST API to indicate that GET requests over large datasets have more content than was returned, in order to allow the API user to paginate

That sounds like a bad idea.

IANA HTTP status code registry currently identifies RFC 9110 as the authoritative definition of the 206 Partial Content status code.

The 206 (Partial Content) status code indicates that the server is successfully fulfilling a range request....

If you aren't already familiar with range requests, review RFC 9110, section 14. But short version: if the incoming request doesn't include a Range header, then you don't have a range request.

Trying to repurpose 206, which has a specific meaning in the general purpose transfer of documents over a network domain, to signal some meaning that is local to your bespoke resource model, increases the possibility that general purpose components misunderstand what is going on; the benefits you hope to realize are unlikely to outweigh the risks.

TL;DR: be normal - return a response with a 200 status code when that's what a boring web server would do.

If you are trying to indicate paging; status code is the wrong tool. Look instead toward Web Linking using link relations like first/last/next/prev.

user_547340
Related