HTTP Requests

To invoke a REST API, your application calls an HTTP operation on the URI associated with a resource. For example, to retrieve the profile information for user whose ID is 3344, an application calls HTTP GET on the following URI:

http://social.yahooapis.com/v1/user/3344/profile

In this example, the profile information is returned in the HTTP response body. Typically, the application checks the response status code for an error and then extracts the data from the response body. For a full list of codes, see the section HTTP Response Codes.

Summary of HTTP Operations

The following table summarizes the HTTP operations for the Yahoo! Social APIs. In the table, the "Singleton or Collection" column indicates whether the operation can be applied to a singleton or collection resource. For example, DELETE applies only to singleton resources, not collections. In this release, all of the APIs support the HTTP GET, HEAD and OPTIONS operations, but only a few of them support the other operations. To see which operations are supported, see the reference section for the related resource in the chapters that follow.

HTTP Operation Singleton or Collection Action
GET Singleton, Collection Retrieves the resource.
HEAD Singleton, Collection Retrieves the header information of a resource.
POST Singleton Creates a new resource.
PUT Singleton Updates a resource.
DELETE Singleton Deletes a resource.
OPTIONS Singleton, Collection Queries a resource to find out what HTTP operations can be performed on the resource.

Retrieving a Resource (GET)

To retrieve a singleton or collection resource, call the HTTP GET operation. If the operation is successful, the HTTP response code is 200 and the response body contains the data that represents the resource. The data can be in the formats listed in Response Formats. By default, the GET operation returns the entire resource. With the view parameter, GET returns certain fields of a singular resource, as described in Retrieving Part of a Singular Resource. To retrieve a subset of a collection resource, you can specify the matrix parameters or a filter within the URI. See Retrieving Part of a Collection Resource for more information.

Creating a Resource (POST)

To create a resource, call the HTTP POST operation, specifying the data for the resource in the entity body. This data can be in the formats listed in Response Formats. If the POST is successful, the HTTP response code is either 200 or 201.

To get the URI of the newly created resource, check the Location header in the response. See the Response Headers section for a full list of headers.

An application can create and delete only singleton resources, not collection resources. Collections are managed by the Web services.

Modifying a Resource (PUT)

To modify an existing resource, call the HTTP PUT operation on the resource's URI, specifying all fields for the resource in the entity body. If the operation is successful, the HTTP response code is either 200, 202, or 204.

Deleting a Resource (DELETE)

To remove an existing resource, call the HTTP DELETE operation on the resource's URI. If the operation is successful, the HTTP response code is either 200 or 202.

Finding Out When a Resource Was Last Modified (HEAD)

To perform this task, call the HEAD operation and then check the Last-Modified header in the HTTP response. The Last-Modified header is set for a singleton resource, but not for a collection. This header is also set in the GET response, but the HEAD response consumes less bandwidth than GET.

Querying the Available Operations on a Resource (OPTIONS)

To find out what HTTP operations can be called on a resource, call the HTTP OPTIONS operation on the resource and then check the Allow response header. If the resource is read-only, the Allow response header is GET, HEAD. If the resource is read-write, the Allow response header contains GET, HEAD, and other available operations such as PUT.

Table of Contents