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:
http://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 be 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 be 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 http://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 http://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: