REST API paging via headers

headerspaginationrest

Let's say I have REST API which provides me list of something and I want to implement paging support – possibility to tell "give me records 20-29 (page 3)". Currently, I don't care about implementation server-side, but about how client tell API he want specific page.

You can pass it in URI (/some-list?page=3) or send it via POST data (you can't use it with GET), but what about headers? Is it good practice (or against something)?

Can I use range or some custom X- header to define, which page (or offset and length) I want to receive?

//EDIT: I also don't care about SEO, search engines etc. My use case is API used internaly in my code.

Best Answer

There are several possible negatives when considering custom header fields.

  1. Browser based testing will be difficult
  2. Proxies sometimes remove/mangle headers fields
  3. It breaks HTTP cacheing
  4. Other developers will not expect it

When returning a dynamic list, you will want cacheing disabled, so that shouldn't be a problem.

If you never expect to use a browser to test your endpoints, you know all the proxies which will be used, and you feel you can document the behavior so future developers won't be surprised by this novel behavior, then try it out.

I've had similar ideas before for HTTP header fields, but they've never worked out. You might have better luck.