HTTP Responses

The next few sections describe some of the syntax and other details of the HTTP Responses of the Yahoo Social APIs. If you are reading this for the first time, you might want to skip ahead and look at the XML and JSON shown in the Response Examples section. All dates in responses are RFC 3339 compliant.

Response Formats

This release of the Yahoo Social APIs supports responses in XML and JSON formats. XML is the default. To set the response format, you can either append the format query parameter to the URI or specify the format in the Accept header of the HTTP request. If both techniques are used, the format parameter of the URI has precedence. For example, if an HTTP GET operation is called on the following URI, the profile data in the response body is in JSON format:

https://social.yahooapis.com/v1/user/3344/profile?format=json

As specified in HTTP Response Codes, the response body can contain the data that represents the resource or an error message. In both cases, the response body is in the selected format, either XML or JSON. The Content-Type header of the response contains the format requested. If the application requests an unsupported format, the response status code is 415.

Note that the order of the fields within response body is not specified and might change. Also, additional fields might be added to a response body. Therefore, your applications should use parsing routines that can extract data from a response body in any order.

The following table lists the values for the formats supported in this release.

Format Type Short Name (Format Query Parameter) Request Accept Header Response Content-Type Header
XML xml application/xml application/xml;charset=UTF-8
JSON json application/json application/json;charset=UTF-8

Common Response Body Attributes

In addition to the resource-specific information, a non-error response body contains meta-data attributes. For example, an XML response body contains the xml:lang attribute, which identifies the human language of the response. For a JSON response, this information is in the object named lang. The following table describes the common attributes in a non-error response body.

XML Attribute Name XPath XML Schema Data Type JSON Object Name Description
yahoo:uri /*/@uri anyURI uri The reference to the actual resource. The value of this attribute is the same as that of the Content-Location header.
xml:lang /*@lang string lang The language of the representation. Examples: de-DE, de-AT, de-BE. The value of this attribute is the same as that of the Content-Language header. The value is an RFC 4646 language tag. See the Language Support section for more information.
yahoo:region /*@region string region A country, for example CA (Canada) or MX (Mexico). The value of this attribute is an ISO 3166 alpha-2 country code. See the Country Identification section for more information.
yahoo:updated /*@updated string updated The last time the resource was updated in the format specified by RFC 3339. If the last modified time is unknown or cannot be calculated, this attribute is not included. This attribute is not required in responses to requests for collections. The value of this attribute is the same as that of the Last-Modified header.
yahoo:created /*@created string created The time the resource was created, in RFC 3339 format. If the last modified time is unknown or cannot be calculated, this attribute is not included. This attribute is not required in responses to requests for collections.
yahoo:start /*@start integer start The index to the first item returned in the collection. See the Paging a Collection section for more information.
yahoo:count /*@count integer count The number of items returned in the collection.
yahoo:total /*@total integer total The total number of items in the collection.

Response Errors

After calling an HTTP request, an application should check the response status code to verify success or detect an error. If the response status code indicates an error, the response body contains an error message. The following table lists the items within the error message:

Item XPath XML Schema Data Type Required or Optional Description
error /error/error element required The root element.
yahoo:uri /error@uri string optional The URI for this error resource.
xml:lang /error/@lang string optional The language of the description. Examples: de-DE, de-AT, de-BE. The value is the same as the value of the Content-Language header.
description /error/description string required A one-line, human-readable description of the error.
detail /error/detail string optional Human-readable details about the error.

Response Examples

XML Response With Singleton Resource

HTTP Request:

GET https://social.yahooapis.com/v1/user/UQIDWJNWVNQD4GXZ5NGMZUSTZZ/contact/378

Response Status Line:

HTTP/1.1 200 OK

Response Header:

Response Body:

XML Response With Collection Resource

Response Body:

XML Response With Error Response

HTTP Request:

GET https://social.yahooapis.com/v1/user/UQIDWJNWVNQD4GXZ5NGMZUSTZZ/contacts

Response Status Line:

HTTP/1.1 404 Resource Not Found

Response Header:

Response Body:

JSON Response With Error Response

Response Body:

Table of Contents