CODEWITHSUNDEEP
javaspringrestrestful-architecture
Himanshu Yadav
Himanshu Yadav

Reputation: 13587

RESTful Service Design: Calling get all resource endpoint

Looking for some suggestions to help me design a restful service.

  1. Get all Products: what happens when a client tries to get all the products /products. Should I return all the products or first 50?
  2. If the service will return the first 50 or the first 100, then where should I write the pagination logic? Should I write it in the same getAllProducts() method?
  3. I am plan to have sort and search functionality as well. Where would these two go?

Here is my assumption:

@RequestMapping("/products")
public String getAllProducts(@QueryParam(value="page") int page, @QueryParam(value="sort") String orderBy) {

@RequestMapping("/search/products")
public String findProducts(@QueryParam(value="q") String searchCriteria) {

Upvotes: 2

Views: 1371

Answers (2)

jbarrueta
jbarrueta

Reputation: 5175

What I recommend is to keep the semantic of your query string simple, words that can be easy to follow by the consumer of the API, for pagination these query parameters can be offset and limit, this way the client is in control of what it will be retrieved, for example:

I might just be interested in the first 2 elements with an offset of 100, which will perform better than if you retrieve a fixed amount every time. Just remember that while the client can set the limit, you should have a max limit value in the Server Side so that you don't end up retrieving all objects and slowing down your application.

A URL representation paginating using offset and limit would be:

GET /products?offset=10,limit=50

Regarding search you also want to use the approach, you must define what attributes of your resources are queryable and order, etc. Also, you might want define a parameter that queries from all the queryable properties (e.g. q) So a request to your collection would look like:

GET /products?offset=10,limit=50,name=*rest*&description=*rest*

or

GET /products?offset=10,limit=50,q=rest

Also I recommend you to check this video about Designing REST + JSON APIs (full disclosure I work at Stormpath, but I truly thing of it as a valuable resource), Les talks about pagination around the 1:00:00, in case you want to fast forward to it.

Hope it helps,

Jose Luis

Upvotes: 1

Robert
Robert

Reputation: 1316

The regular practice, as you suggested, is to use parameters.
Depending on your requirements you could use one of theese:

  1. ?page=$pagenumber (with pagesizes defined by you)
  2. ?page=$pagenumber?per_page=$pagesize (with pagesizes defined by client) (Thats GitHubs way of doing it)
  3. ?start=$idOfFirstElement?per_page=$idOfLastElement (no "artifical" pages, nearer to database)

Of course you could (or maybe should) restrict the input for variant 2 and 3, and if the result is to big, give back a #4XX response code.

  1. Get all Products: what happens when a client tries to get all the products /products. Should I return all the products or first 50?

The regular and expected RESTful behavior would be to get all products, while in real environments often that's not possible. (Just think of "small" webshops with 10k products).
Basically you have two design options:

  1. A HTTP request without paging information is bad. Give an #4XX response.
  2. A HTTP request without paging information uses default values. (e.g. first page and 50 products per page)

I would suggest using the first one, as it looks much cleaner and there will be no confusion for clients.

  1. I am plan to have sort and search functionality as well. Where would these two go?

Same as with the page parameters. Just add them to the URI.
e.g. ?sortBy="price" ?sort="ASC" ?sort="DESC" ?searchFor="lalalala"

  1. If the service will return the first 50 or the first 100, then where should I write the pagination logic? Should I write it in the same getAllProducts() method?

Sadly we cannot really comment on that with your small amount of given code. ...And SO isn't really for Code Review

Upvotes: 1

Related Questions