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:

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:;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.) Search strings used with filter expressions must be URI-escaped and UTF-8 encoded. For example, a search string for an email address would have to escape the '@' character to '%40'.

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.

Table of Contents