Uniform Resource Identifiers (URIs)

REST-based Web services are organized into resources. A resource is a chunk of related information, such as a user profile, a collection of updates (activities), or a global user ID (GUID). Each resource is identified by one or more Uniform Resource Identifiers (URIs). To access the resource, an application calls an HTTP operation on one of the resource's URIs.

Singleton and Collection Resources

The resources described in this guide fall into two categories: singleton and collection. A singleton resource is a single chunk of information, similar to a row in a database table. A collection resource is a set of resources with the same structure, similar to a selection of rows in a database table. Applications process singleton and collection resources differently. For example, applications can apply paging and filtering techniques to collection resources, but not to singleton resources. Another difference is that some HTTP operations are not allowed on collection resources.

URI Syntax

The URIs for Yahoo REST-based Web services have the following syntax:

https://{service}.yahooapis.com/{version}/{resourcepath}

The elements in this syntax are as follows:

  • {service} - The name of the Yahoo Web service. For the Yahoo Social APIs, the service name is social.
  • {version} - The version of the APIs. In this release, the version is v1.
  • {resourcepath} - A path that defines a singleton resource or a collection of resources. Every {resourcepath} includes a unique ID. The right-to-left ordering of elements in {resourcepath} indicate containment. The example URIs that follow show these different styles of {resourcepath}.

Important

The elements {version} and {resourcepath} are case-sensitive.

URI Examples

The following URI defines the profile resource for the user whose ID is 12345.

https://social.yahooapis.com/v1/user/12345/profile

The next URI specifies the connections (friends) for the user whose ID is 6677.

https://social.yahooapis.com/v1/user/6677/connections

The following URI accesses the collection of schools contained in the profile of the user of ID 98765.

https://social.yahooapis.com/v1/user/98765/profile/schools

URI Parameters

The URIs in this guide permit two types of URI parameters: query and matrix. Both parameter types are case-sensitive unless specified otherwise by an API. To find out which parameters are supported for a particular URI, check the reference sections in the following chapters.

Query Parameters

The following table lists the query parameters that might be supported by a resource.

Parameter Data Type Description
format string The content type, either xml or json. For details, see Response Formats
lang string The desired human languages for a representation, for example: "es-US,es-ES,en-US". The value is a comma-separated list of RFC 4646 basic language ranges in descending priority order. For details, see Language Support.
region string The ISO 3166-1 alpha-2 country code that specifies the desired region for a representation. For details, see Country Identification.
callback string The callback function. This parameter is for JSON requests only. For details, see Using callback=function.
view string The name of a rule in a Web service's RELAX NG schema file by which a named (partial) representation of a resource can be retrieved. This parameter enables you to retrieve a subset of the fields contained within a resource. For details, see Retrieving Part of a Singular Resource.
Matrix Parameters

Matrix parameters enable the application to retrieve part of a collection when calling an HTTP GET operation. See Paging a Collection for an example. Because matrix parameters can follow any collection path segment in a URI, they can be specified on an inner path segment. Multiple matrix parameters can be used in a given URI. Note that a matrix parameter is preceded by a semicolon.

Parameter Data Type Description
start integer The first item in the collection to be returned by GET. The default is 0.
count integer The number of items in the collection to be returned by GET. The default is 10.

Table of Contents