RESTful URLs: "Impractical" Requests, and Requiring One of Two Request Parameters...

Question

I have a RESTful URL that requires either the offset or the prefix request parameter (but not both).

GET /users?offset=0&count=20
GET /users?prefix=J&count=20

What's the best way to enforce this rule? Spring has the @RequestParam annotation with the 'required' property for optional parameters, but I want to enforce an "either-or" rule on these two parameters. I know I could do it in the code, but is there another way to do it?

Also, what's the proper way to handle "impractical" requests? Say I have 100 million users; the following request, although properly RESTful, is not something I want to support:

GET /users <-- Gets all 100 million users, crashes server and browser!

What should I send back?

Answer 1

You can create two methods and choose one of them with @RequestMapping's params attribute:

@RequestMapping(..., params = {"prefix", "!offset"})
public String usersWithPrefix(@RequestParam("prefix") ...) { ... }

@RequestMapping(..., params = {"offset", "!prefix"})
public String usersWithOffset(@RequestParam("offset") ...) { ... }

Answer 2

• what's the proper way to handle "impractical" requests?

The lesser-practiced principles of REST include the requirement that resources be "discoverable". If you are asked for a complete list of 800 million users and you don't want to provide it, you might instead consider serving a page that describes in some way how to filter the collection: for example, an XForms document or HTML containing a FORM element with fields for offset/prefix/count, or a URI template with the appropriate parameters

Or you could just send a "413 Entity too large" error - edit: no you can't. Sorry, I misread the description of whath this code is for

If you decide to go down the route of just sending the first page, I think I would send it as an HTTP redirect to /users?offset=0&count=20 so that the client has a better idea they've not got the full collection (and if your response contains a link to access subsequent pages, even better)