2

I am currently writing an REST API using the Jersey Framework. I am following the HATEOAS principle and the user should only be moving through the api by the given links in my response body oder headers. On some Resources I have implemented pagination functionality. I was wondering though, what should I tell the User (HTTP Status Code), when he is not following my boundaries and just like randomly makes a request where the requested page is actually "out of bounds". Currently I just return a null Collection, but I think as a User, I wouldn't be able to make something out of such a response. I considered using the Status Code "Not Found", but I am not sure if that is the appropriate one. I really want to stay true to REST and that implicates I stay true to HTTP. So can anyone give me suggestions or even tell me if there is actually a rule for my problem?

Maybe a concrete example:

  • page size = 10;
  • Collection.size = 27;
  • requested page = 4;
  • Paging starts with page 0

, so requesting http://...../resource?page=0, returns the first page. My question is, what should I return for the request http://...../resource?page=4? Currently I am just returning null, but I don't think that's the proper response. Thanks in advance

EDIT: I am only asking about the expected Response in case the requested page is "empty". I know that fixed page size design may be doomed for future change requests, but since this API is part of a Microservice, there will be none, except we have a fight inside our team :)

kasokz
  • 93
  • 7
  • Possible duplicate of [Pagination in a REST web application](http://stackoverflow.com/questions/776448/pagination-in-a-rest-web-application) –  Jun 28 '16 at 06:56

1 Answers1

-2

404 not found is the appropriate return code for an out of bound access.

But you should consider change your resource identifier (URI). Returning 404 or 200 depending on a URL parameter is not a good design.

It would be better to treat every page as single resource. That's also true for HATEOAS.

 .../resource/page/0  #200 + return link in header to next resource  .../resource/page/1
 .../resource/page/4  #404 + return link to first resource  .../resource/page/0)

Using URL parameters should be the last option if nothing else works (for example range access).

Paul Wasilewski
  • 9,762
  • 5
  • 45
  • 49
  • All right, thank you! I will try that. I actually learned about pagination using offset and size only and thought, that if I want to use fixed sizes, I could just use a page parameter. Never actually thought about using a page as a resource. – kasokz Jun 26 '16 at 18:04
  • 2
    That's decidedly nonstandard, because it makes life hard for clients when they want to change offset or page size. It also restricts them to the "page" concept, when not all clients think in those terms. – Eric Stein Jun 27 '16 at 12:50
  • 1
    @EricStein, if you are using a non fixed page size you have to access paginate the resource through URL parameters, but if you are using a fixed page size accessing throug a page is absolutely fine and imho the right concept. – Paul Wasilewski Jun 27 '16 at 14:40
  • 1
    @PaulWasilewski It works great until the requirements change and you need to support variable page sizes. Then it's either an ugly hack (`GET /page/0?size=25`) or a breaking change. – Eric Stein Jun 27 '16 at 14:48
  • @EricStein, OP mentioned that the page size is fixed explicitly. – Paul Wasilewski Jun 27 '16 at 18:24
  • 2
    Yes, it is today. Tomorrow, though, it's a breaking change. You're making a permanent decision on a requirement that will probably change. – Eric Stein Jun 27 '16 at 18:32
  • 1
    @PaulWasilewski OP did not mention the page size is fixed explicitly. He said here is a *concrete example* – jfadich Jun 27 '16 at 18:40
  • 1
    @kasokz As mentioned by EricStein using a get parameter is probably a more future proof option. If there are only 4 pages and they request page 5 I would just return an empty array. – jfadich Jun 27 '16 at 18:43
  • @jfadich, imagine you are using a next button and you are requesting page5 will you show an empty page or no content after the action? Anyway I will improve my answer and include a second (and more future proofen) solution. – Paul Wasilewski Jun 27 '16 at 20:17
  • @PaulWasilewski Well this is a REST API so there isn't a 'next button'. Although I usually will include a 'meta' section in the response that will tell you how many pages and/or resources there are. It's up to the client to decide how to handle an empty response. I would probably just show a "No results" page – jfadich Jun 27 '16 at 20:22
  • @jfadich, the next button was just an example, and of course upon many RESTApi is a next button implemented for example Google. And OP also mentioned he want to ensure that his API is HATEOS driven. Returning an empty result have nothing to do being HATEOS. – Paul Wasilewski Jun 27 '16 at 20:32
  • 1
    Hey all, sorry for the confusion that stirred up some of your discussions. I have indeed chosen to implement pagination of this resource with fixed size, because my specific REST-API's target is mobile applications, where a page is pretty predictable. My team and I are making this API as a part of a microservice, where we actually don't care about others than us using this API. So we decided on a fixed Page size for less "freedom" on client side. As I said, I learned about Pagination actually using offset & size, but I was specifically asking about fixed size pages. Thank you all though! :) – kasokz Jun 28 '16 at 19:40