Response Types
The Digg API provides several response types, each designed to be useful in a variety of programming contexts:
- [#XMLXML]: Easily parsed in many languages on many platforms. It is particularly easy to use in Flash applications.
- [#JSON
JSON]: May be directly eval'd in Javascript, and also can be parsed in many languages. - [#JavascriptJavascript]: Useful as the source of a script tag, it passes JSON response to the Javascript callback function you specify.
- [#PHP
Serialized PHP]: Easily unserialized in PHP to create objects, to which the programmer can attach custom methods. Or the programmer can directly access the response data through the public properties of the objects.
How to Specify the Response Type
The request can specify the desired response type in either of two ways:
The type argument, if present, overrides the Accept header.
The Accept header works by specifying one or more acceptable media types and a "quality factor" for each. The Digg API selects the media type with the highest quality factor from the list below and uses the corresponding response type:
- text/xml: XML response type
- application/json: JSON response type
- text/javascript: Javascript response type
- application/php: Serialized PHP response type
If more than one media type have equal quality factors, the Digg API selects the first from the list. If none of the listed media types are acceptable, the XML response type is used.
Response Content Type
The response indicates the response type in the HTTP Content-Type header:
- XML: Content-Type: text/xml;charset=utf-8
- JSON: Content-Type: application/json
- Javascript: Content-Type: text/javascript;charset=UTF-8
- Serialized PHP: Content-Type: application/php
Details
XML
XML responses use Digg's custom XML format.
Example request:
http://services.digg.com/topics?appkey=http%3A%2F%2Fexample.com&type=xml
Here are the HTTP headers for an example request with no type argument and a broad Accept header. Since all response types are acceptable, the Digg API selects the XML response type.
GET /user/sbwms?appkey=http%3A%2F%2Fexample.com HTTP/1.1
Host: services.digg.com
Accept: */*
...
HTTP/1.1 200 OK
Content-Type: text/xml;charset=UTF-8
Content-Length: 227
JSON
JSON (JavaScript Object Notation, json.org) is a lightweight data-interchange format. It is a subset of valid Javascript and Python, and is especially suited for use in Ajax applications running in a web browser. Requests made from Javascript running on your web pages must be proxied to avoid same-origin policy conflicts.
- Type argument: json.
- Media type: application/json.
Example request:
http://services.digg.com/topics?appkey=http%3A%2F%2Fexample.com&type=json
Example HTTP headers:
In the first example, the type argument selects the JSON response type, overriding the XML response type selected by the Accept header.
GET /user/sbwms?appkey=http%3A%2F%2Fexample.com&type=json HTTP/1.1
Host: services.digg.com
Accept: */*
...
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 184
In the next example, the Accept header selects the JSON response type.
GET /user/sbwms?appkey=http%3A%2F%2Fexample.com HTTP/1.1
Host: services.digg.com
Accept: application/json
...
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 184
Javascript
The Javascript response type decodes the JSON response and passes the data to a Javascript callback function you specify in the callback argument in the request. This is useful when the API request is the source of a script tag, because Javascript code inserted into the page in this way is not subject to the same-origin policy, so no proxy is required.
Your callback function can display the response data in your web page or process it in some other way.
Note that we use this technique on this documentation web site to display the current list of errors that may be returned by the API and the current set of Digg topics.
- Type argument: javascript.
- Media type: text/javascript.
Example usage:
<script type="text/javascript">
function myfunc(obj) {
alert(obj);
}
</script>
<script type="text/javascript" src="http://services.digg.com/topics?appkey=http%3A%2F%2Fexample.com&type=javascript&callback=myfunc"></script>
Example HTTP headers:
In the first example, the type argument selects the Javascript response type, overriding the XML response type selected by the Accept header.
GET /user/sbwms?appkey=http%3A%2F%2Fexample.com&type=javascript&callback=myfunc HTTP/1.1
Host: services.digg.com
Accept: */*
...
HTTP/1.1 200 OK
Content-Type: text/javascript
Content-Length: 184
In the next example, the Accept header selects the Javascript response type.
GET /user/sbwms?appkey=http%3A%2F%2Fexample.com&callback=myfunc HTTP/1.1
Host: services.digg.com
Accept: application/javascript
...
HTTP/1.1 200 OK
Content-Type: text/javascript
Content-Length: 184
PHP
Serialized PHP responses can be PHP's unserialized to create PHP objects. The public properties of those objects may be accessed directly.
If the programmer defines the classes of the names used in the serialized PHP response, those classes may include methods that operate on the data in the objects.
The serialized PHP responses are in the form used by PHP 5, but we believe that PHP 4 can unserialized the data into usable objects.
Example request:
http://services.digg.com/topics?appkey=http%3A%2F%2Fexample.com&type=php
Example usage in PHP 5:
class DiggAPITopic {
public function sayName() {
echo "$this->name\n";
}
}
class DiggAPITopics {
public function sayTopics() {
foreach ($this->topics as $topic) {
$topic->sayName();
}
}
}
ini_set('user_agent', 'My-Application/2.5');
$uri = 'http://services.digg.com/topics?appkey=http%3A%2F%2Fexample.com&type=php';
$response = file_get_contents($uri);
$topics = unserialize($response);
$topics->sayTopics();
Comments (0)
You don't have permission to comment on this page.