Try the beta version of the new SilverStripe documentation

For the next 2 weeks you can use the new documentation website and give us your feedback.

close

Restful Service

Introduction

RestfulService uses the php curl library, enabling connections to remote web services which support a REST interface and consuming those web services. (Examples: Flickr, Youtube, Amazon and etc). RestfulService can parse the XML response (sorry no JSON support) returned from the web service. Further it supports caching of the response, and you can customize the cache interval.

To gain the functionality you can either create a new RestfulService object or create a class extending the RestfulService (see flickrservice and youtubeservice modules).

Examples

Creating a new RestfulObject

//example for using RestfulService to connect and retrive latest twitter status of an user.
$twitter = new RestfulService("http://twitter.com/statuses/user_timeline/user.xml", $cache_expiry );
$params = array('count' => 1);
$twitter->setQueryString($params);
$conn = $twitter->request();
$msgs = $twitter->getValues($conn, "status");

Extending to a new class

//example for extending RestfulService
class FlickrService extends RestfulService {
    public function __construct($expiry=NULL){
        parent::__construct('http://www.flickr.com/services/rest/', $expiry);
        $this->checkErrors = true;
    }
......

Multiple requests by using the $subURL argument on connect()

// Set up REST service
$service = new RestfulService("http://example.harvestapp.com");
$service->basicAuth('username', 'password');
$service->httpHeader('Accept: application/xml');
$service->httpHeader('Content-Type: application/xml');
$peopleXML = $service->request('/people');
$people = $service->getValues($peopleXML, 'user');
// ...
$taskXML = $service->request('/tasks');
$tasks = $service->getValues($taskXML, 'task');

Features

Caching

To set the cache interval you can pass it as the 2nd argument to constructor.

new RestfulService("http://twitter.com/statuses/user_timeline/user.xml", 3600 );

Getting Values & Attributes

You can traverse throught document tree to get the values or attribute of a particular node. for example you can traverse

<entries>
     <entry id='12'>Sally</entry>
     <entry id='15'>Ted</entry>
     <entry id='30'>Matt</entry>
     <entry id='22'>John</entry>
</entries>

to extract the id attributes of the entries use:

$this->getAttributes($xml, "entries", "entry") //will return all attributes of each entry node

to extract the values (the names) of the entries use:

$this->getValues($xml, "entries", "entry") //will return all values of each entry node

Searching for Values & Attributes

If you don't know the exact position of dom tree where the node will appear you can use xpath to search for the node.Recommended for retrieving values of namespaced nodes.

<media:guide>
     <media:entry id="2030">video</media:entry>
</media:guide>

to get the value of entry node with the namespace media, use:

$this->searchValue($response, "//media:guide/media:entry")

Best Practices

Handling Errors

If the web service returned an error (for example, API key not available or inadequate parameters) RestfulService could delgate the error handling to it's descendant class. To handle the errors define a function called errorCatch

// This will raise Youtube API specific error messages (if any).
public function errorCatch($response){
    $err_msg = $response;
     if(strpos($err_msg, '<') === false) {
         user_error("YouTube Service Error : $err_msg", E_USER_ERROR);
     }
     return $response;
}

If you want to bypass error handling on your sub-classes you could define that in the constructor.

public function __construct($expiry=NULL){
    parent::__construct('http://www.flickr.com/services/rest/', $expiry);
    $this->checkErrors = false; //Set checkErrors to false to bypass error checking
}

Other Uses

How to use RestfulService to easily embed an RSS feed

RestfulService can be used to easily embed an RSS feed (since it's also an xml response) from a site such as del.icio.us

Put something like this code in mysite/code/Page.php inside class Page_Controller

// Accepts an RSS feed URL and outputs a list of links from it
public function RestfulLinks($url){
    $service     = new RestfulService($url);
    $request     = $service->request();
    $body         = $request->getBody();
    $items         = $service->getValues($body,"channel","item");    
    $output = '';
    foreach($items as $item) {
        // Fix quote encoding
        $description = str_replace('&amp;quot;', '&quot;', $item->description);
        $output .=  "<li><a href=\"{$item->link}\">{$item->title}</a><br />{$description}</li>";
    }
    return $output;
} 

Put something like this code in themes/<your-theme>/templates/Layout/HomePage.ss:

<h3>My Latest Del.icio.us Links</h3>
<ul>
    $RestfulLinks(http://del.icio.us/rss/elijahlofgren) 
</ul>

API Documentation

RestfulService

Comments

Comment policy: Please use comments for tips and corrections about the described functionality.
Comments are moderated, we reserve the right to remove comments that are inappropriate or are no longer relevant. Use the Silverstripe Forum to ask questions.

blog comments powered by Disqus