Getting the number of returns visible with a RESTful request

Question

So, I would like to know how many results I get back from a RETful uri GET request. At the moment, I do not know how to do this. Is there any way to do this? Since REST just throws away the properties, I don’t know if it is able to calculate its results, but it can skip the results and take a subset of the results.

Anyone have any suggestions?

Oh, my setup is LINQ to SQL, which populates a list with a common set. The data service makes this list available. I tried to get the score in the list, but I always return the maximum rows of the database, and that is not what I am looking for.

Answer 1

Other people may object to this concept, but it seems reasonable to me:

HEAD /your/api HTTP/1.1 HTTP/1.1 200 OK Date: Fri, 23 Oct 2009 00:58:17 GMT Content-Type: application/xml; charset=UTF-8 Content-Length: 89 X-Result-Count: 100000000 

And then:

 GET /your/api HTTP/1.1 HTTP/1.1 200 OK Date: Fri, 23 Oct 2009 00:58:17 GMT Content-Type: application/xml; charset=UTF-8 Content-Length: 89 X-Result-Count: 100000000 <?xml version="1.0" encoding="UTF-8"?> <results> 100000000 results go here. </results> 

Note: A HEAD request is used here to get a counter without having to pull out a complete set of data. HEAD requests retrieve only HTTP headers, not the response body.

This would be the most RESTful way, I can think about how many results you get before sending it over the wire. The main trick is just right for the best headline for him. X-Result-Count is decent, but if you can find the previous level and reuse your header selection, it will be even better (unless they call it something really stupid). However, I do not expect you to have much luck, so you should stick with the X-Result-Count .

Also, I think you may have misunderstood what “REST” actually means. There is no reason why you cannot provide a range view. For example:

 GET /your/api?page=1&perpage=10 HTTP/1.1 HTTP/1.1 200 OK Date: Fri, 23 Oct 2009 00:58:17 GMT Content-Type: application/xml; charset=UTF-8 Content-Length: 101 X-Result-Count: 10 <?xml version="1.0" encoding="UTF-8"?> <results> First 10 results of 100000000 go here. </results> 

However, to be RESTful, you must be able to tell the client about the view identified by /your/api?range=0-9 or /your/api?page=1&perpage=10 , without using information out of range. For example, if your page /your/api returns too many results, temporarily redirect to /your/api?page=1&perpage=10 and enable hyperlinks to /your/api?page=2&perpage=10 . Note that a hyperlink in this context may be something simple:

 <?xml version="1.0" encoding="UTF-8"?> <results> <result> This is a result. </result> <result> This is also a result. </result> <link rel="next" href="/your/api?page=3&perpage=2" /> <link rel="prev" href="/your/api?page=1&perpage=2" /> </results> 

Now the information for navigating the results of your API calls is in-band and virtually RESTful.

In essence, REST is simple HTTP code with caching done correctly and usually sensitive URIs that have been chosen for good measure. It is also “hypertext as an application state mechanism” (that is, resources must refer to other resources). This is not a protocol, this is an architectural style. Anyone who tells you differently is best called Roy Fielding.

• http://roy.gbiv.com/untangled/2009/it-is-okay-to-use-post
• http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven
• http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven#comment-718

Addenda:

If you want to specify a total counter versus the number of pages, you can define the title as follows:

 X-Result-Count: 0-9/100000000 

Or adjust as needed.

Answer 2

Why don't REST web services return data as JSON or XML, and there you can have a property about the length.

Answer 3

You can take care of this in your REST resource name design. You will start with something like:

• / widget / 12345 (widget view 12345)
• / widgets (list of all widget resource names, i.e. links)

You can quickly decide that "/ widgets" will be an extensive list and decide to support pages, something like

• / widgets / page / 43 (this may have links to the 4200th-4299th widgets and additional information such as the total number of pages or the number of widgets.)

In other cases, you can divide a large set into a natural hierarchy:

• / widgets / mahogany, / widgets / oak, ...
• / movies / drama, films / romance, ...
• / computers / hard drives / seagate, / computers / usbdrives / kingston

And you can also ask for queries:

• / widgets maxprice = 200 &? Maxweight = 4

Answer 4

Why don't you handle resource handler requests for this type of metadata? Let's pretend that

 GET /items 

returns a list of such elements:

 <items count="5" modified="2009-10-22"> <item url="/items/first" name="First Item" /> <item url="/items/second" name="Second Item" /> ... </items> 

Then something like:

 GET /items?info 

may return an empty list:

 <items count="5" modified="2009-10-22" type="info" /> 

or possibly a general white paper:

 <info> <items count="5" modified="2009-10-22" url="/items" /> </info> 

You can also implement the info resource, for example:

 GET /info?items&users 

which may return:

 <info> <items count="5" modified="2009-10-22" url="/items" /> <users count="8" modified="2009-10-05" url="/users" /> </info>