mirror of
https://github.com/silverstripe/silverstripe-framework
synced 2024-07-30 07:26:21 +02:00
82ed86f6cd
- Correct internal links between documentation pages - Delete defunct links to documentation removed during documentation reorganization - Restore testing glossary - Verify by crawling site locally
177 lines
4.3 KiB
Markdown
177 lines
4.3 KiB
Markdown
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.
|
|
|
|
<div class="alert" markdown="1">
|
|
RestfulService currently only supports XML. It has no JSON support at this stage.
|
|
</div>
|
|
|
|
## 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
|
|
<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:
|
|
|
|
:::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.
|
|
|
|
<div class="note">
|
|
This is the recommended method for retrieving values of name spaced nodes.
|
|
</div>
|
|
|
|
:::xml
|
|
<media:guide>
|
|
<media:entry id="2030">video</media:entry>
|
|
</media:guide>
|
|
|
|
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
|
|
<?php
|
|
|
|
class MyRestfulService extends RestfulService {
|
|
|
|
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, define `checkErrors` in the constructor for `RestfulService`
|
|
|
|
:::php
|
|
<?php
|
|
|
|
class MyRestfulService extends RestfulService {
|
|
|
|
public function __construct($expiry = NULL) {
|
|
parent::__construct('http://www.flickr.com/services/rest/', $expiry);
|
|
|
|
$this->checkErrors = false;
|
|
}
|
|
}
|
|
|
|
## How to's
|
|
|
|
* [Embed an RSS Feed](how_tos/embed_rss)
|
|
|
|
## API Documentation
|
|
|
|
* `[api:RestfulService]`
|