summary: Consume external data through their RESTFul interfaces.
# Restful Service
`[api:RestfulService]` is used to enable connections to remote web services through PHP's `curl` command. It provides an
interface and utility functions for generating a valid request and parsing the response returned from the web service.
RestfulService currently only supports XML. It has no JSON support at this stage.
## Examples
### Creating a new RestfulObject
`getWellingtonWeather` queries the Yahoo Weather API for an XML file of the latest weather information. We pass a query
string parameter `q` with the search query and then convert the resulting XML data to an `ArrayList` object to display
in the template.
**mysite/code/Page.php**
:::php
public function getWellingtonWeather() {
$fetch = new RestfulService(
'https://query.yahooapis.com/v1/public/yql'
);
$fetch->setQueryString(array(
'q' => 'select * from weather.forecast where woeid in (select woeid from geo.places(1) where text="Wellington, NZ")'
));
// perform the query
$conn = $fetch->request();
// parse the XML body
$msgs = $fetch->getValues($conn->getBody(), "results");
// generate an object our templates can read
$output = new ArrayList();
if($msgs) {
foreach($msgs as $msg) {
$output->push(new ArrayData(array(
'Description' => Convert::xml2raw($msg->channel_item_description)
)));
}
}
return $output;
}
## Features
### Basic Authenication
:::php
$service = new RestfulService("http://example.harvestapp.com");
$service->basicAuth('username', 'password');
### Make multiple requests
:::php
$service = new RestfulService("http://example.harvestapp.com");
$peopleXML = $service->request('/people');
$people = $service->getValues($peopleXML, 'user');
// ...
$taskXML = $service->request('/tasks');
$tasks = $service->getValues($taskXML, 'task');
### Caching
To set the cache interval you can pass it as the 2nd argument to constructor.
:::php
$expiry = 60 * 60; // 1 hour;
$request = new RestfulService("http://example.harvestapp.com", $expiry );
### Getting Values & Attributes
You can traverse through document tree to get the values or attribute of a particular node using XPath. Take for example
the following XML that is returned.
:::xml
Sally
Ted
Matt
John
To extract the id attributes of the entries use:
:::php
$this->getAttributes($xml, "entries", "entry");
// array(array('id' => 12), array('id' => '15'), ..)
To extract the values (the names) of the entries use:
:::php
$this->getValues($xml, "entries", "entry");
// array('Sally', 'Ted', 'Matt', 'John')
### 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.
This is the recommended method for retrieving values of name spaced nodes.
:::xml
video
To get the value of entry node with the namespace media, use:
:::php
$this->searchValue($response, "//media:guide/media:entry");
// array('video');
## Best Practices
### Handling Errors
If the web service returned an error (for example, API key not available or inadequate parameters),
`[api:RestfulService]` can delegate the error handling to it's descendant class. To handle the errors, subclass
`RestfulService and define a function called errorCatch.
:::php
checkErrors = false;
}
}
## How to's
* [Embed an RSS Feed](how_to/embed_rss)
## API Documentation
* `[api:RestfulService]`