I would like to know what's the best approach for my RESTful app when requesting all records.
For example, I limit my responses to 10 if no $top value is provided to avoid overload. However, how can I format my request? Which is better, $top=allrows or $top=all? Is there any pattern I should check for?
If $top value is not provided I only return up to 10 rows.
GET /products?$top=
I just want to avoid this:
GET /products/all
There's no official pattern and any choice would depend on the size of your data.
Whatever you do, always put a maximum limit to the number of items you'll return regardless of parameters the client provides in the request.
Also, create a default count to return when no information is provided by parameters.
If you don't have tons of items to return, you count set your default count to be max limit and that be enough to always return all and you could just make the url without any details on specific counts return all.
GET /products (no count/provided)
If you have hundreds or thousands and you have a default count of say 100, maybe use something a explicit count to extend that limit (up to the max of course--if asking for count > max, return a 400 bad request with message indicating count can't be higher than max)
GET /products?count=1000000
However, this could be horrible for your server(s) and/or the client if you keep pushing the max limit higher and higher.
Typically, if you've a lot of records, you chunk it up and use a count and offset to pull it down in byte-sized chunks. Also add meta data to the response object letting the requester know the current position, total records, and offset supplied
A little pseudo-code:
$count = 1000
$offset = 0
While count*offset < total records:
GET /products?count=$count&offset=$offset
$offset = $offset + $count
Assuming one of the requests looks like:
GET /products?count=1000&offset=1000
Then in the response body you'd expect something like:
{
"result": [
{
"id": "123",
"name": "some product",
"link": "/product/123"
},
... many more products ...
{
"id": "465",
"name": "another product",
"link": "/product/465"
}
],
"meta": {
"count": 1000,
"offset": 1000,
"total_count": 3000,
"next_link": "/products?count=1000&offset=2000",
"prev_link": "/products?count=1000&offset=0",
},
"status": 200
}
If you really want gold star you can make your resources adhere to HATEOS ( https://en.wikipedia.org/wiki/HATEOAS ) and include links to the individual resources in the list and maybe in the meta have links to the next and prior chunks of the list if you're walking a large list of items. I've put some example links in the json sample above.
I would do it like that:
For all products GET /products
For certain product GET /products/{id}
For all products with filtering or sorting, use GET /products but let the client send you Filter object in request body. There it can specify if he wants certain page in pagination, or filter some records etc.
Filter Object could look like: {"pageNumber":1,"pageSize":12,"freeText":"","conditions":[],"sortings":{}} In your service map it to inner service filter and return the requested records.
