Retrieving Partial Resources
By default, a GET operation returns the entire resource. The
following sections explain how to get a partial resource during a
GET.
Retrieving Part of a Singular Resource
A resource might provide different views of the same data. To
specify a view, append the view query parameter to
the URI. For example, to retrieve the tiny view of the contacts for the
user of GUID 4467, call HTTP GET on the following URI:
http://social.yahooapis.com/v1/user/4467/contacts?view=tinyusercard
Note that the view parameter applies only to
singleton (not collection) resources.
Retrieving Part of a Collection Resource
Matrix parameters (paging) and filters enable an application to
limit the number of collection resources returned by a GET operation.
The structure of each resource within the retrieved collection is
unchanged. In other words, matrix parameters and filters do not
determine which fields within a resource are retrieved.
Paging a Collection
If a GET operation returns many items in a collection, you might
want your application to page through the items. To indicate paging,
specify the start and count
matrix parameters with the
URI. Calling GET on the following URI, for example, returns the first
20 connections for user 6677:
http://social.yahooapis.com/v1/user/6677/connections;start=0;count=20
The default values for start and
count are 0 and 10, respectively. Therefore, if you
do not specify these values, the GET operation returns the first ten
resources in a collection.
To find the total number of items in collection, call the GET
operation and check the total attribute in the
response body. If the response format is XML, check the
yahoo:total attribute of the root element. If the
format is JSON, check the object named
total.
The response body contains values for total,
start, and count. For details,
see the table in the Common Response Body Attributes section.
Filtering a Collection
With a filter, you can limit the number of resources returned by
an HTTP GET operation to only those items that are of interest to your
users. To specify such a filter, you include filter expression in the
collection's URI. A filter expression is analogous to a WHERE clause
of a SQL statement. (Unlike a WHERE clause, which can refer to
multiple tables, a filter expression applies to only one
collection.)
Only some collection resources support filters, and the filter syntax is different for each resource. For details on constructing filters for a particular resource, see the corresponding Filter section later in this guide. A filter cannot span multiple collections.