Alirio Alirio - 12 days ago 5
reST (reStructuredText) Question

What's the pattern to request for all records using RESTful app?

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? Is good $top=allrows or $top=all?. Is there any pattern shoud I check?.

If not $top value is provided I only return up to 10 rows.

GET /products?$top=


I just want to avoid this:

GET /products/all


Thanks in advance,

Alirio.

Ray Ray
Answer

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 however for your server 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.

Comments