Added first cut of RestfulServer - simple get support

git-svn-id: svn://svn.silverstripe.com/silverstripe/open/modules/sapphire/trunk@51861 467b73ca-7a2a-4603-9d3b-597d59a354a9
This commit is contained in:
Sam Minnee 2008-03-30 23:18:04 +00:00
parent 0b577aa401
commit e747282dfa
5 changed files with 253 additions and 0 deletions

178
api/RestfulServer.php Normal file
View File

@ -0,0 +1,178 @@
<?php
/**
* Sapphire's generic RESTful server.
*
* NOTE: This is an alpha module and its API is currently very volatile. It functions, but it might change radically
* before the next release!
*
* This class gives your application a RESTful API for free. All you have to do is define static $api_access = true on
* the appropriate DataObjects. You will need to ensure that all of your data manipulation and security is defined in
* your model layer (ie, the DataObject classes) and not in your Controllers. This is the recommended design for Sapphire
* applications.
*
* - GET /api/v1/(ClassName)/(ID) - gets a database record
* - GET /api/v1/(ClassName)/(ID)/(Relation) - get all of the records linked to this database record by the given reatlion (NOT IMPLEMENTED YET)
* - GET /api/v1/(ClassName)?(Field)=(Val)&(Field)=(Val) - searches for matching database records (NOT IMPLEMENTED YET)
*
* - PUT /api/v1/(ClassName)/(ID) - updates a database record (NOT IMPLEMENTED YET)
* - PUT /api/v1/(ClassName)/(ID)/(Relation) - updates a relation, replacing the existing record(s) (NOT IMPLEMENTED YET)
* - POST /api/v1/(ClassName)/(ID)/(Relation) - updates a relation, appending to the existing record(s) (NOT IMPLEMENTED YET)
*
* - DELETE /api/v1/(ClassName)/(ID) - deletes a database record (NOT IMPLEMENTED YET)
* - DELETE /api/v1/(ClassName)/(ID)/(Relation)/(ForeignID) - remove the relationship between two database records, but don't actually delete the foreign object (NOT IMPLEMENTED YET)
*
* - POST /api/v1/(ClassName)/(ID)/(MethodName) - executes a method on the given object (e.g, publish)
*/
class RestfulServer extends Controller {
protected static $api_base = "api/v1/";
/**
* This handler acts as the switchboard for the controller.
* Since no $Action url-param is set, all requests are sent here.
*/
function index() {
ContentNegotiator::disable();
$requestMethod = $_SERVER['REQUEST_METHOD'];
$className = $this->urlParams['ClassName'];
$id = $this->urlParams['ID'];
switch($requestMethod) {
case 'GET':
return $this->getHandler($className, $id);
case 'PUT':
return $this->putHandler($className, $id);
case 'DELETE':
return $this->deleteHandler($className, $id);
case 'POST':
}
}
/**
* Handler for object read.
*
* The data object will be returned in the following format:
*
* <ClassName>
* <FieldName>Value</FieldName>
* ...
* <HasOneRelName id="ForeignID" href="LinkToForeignRecordInAPI" />
* ...
* <HasManyRelName>
* <ForeignClass id="ForeignID" href="LinkToForeignRecordInAPI" />
* <ForeignClass id="ForeignID" href="LinkToForeignRecordInAPI" />
* </HasManyRelName>
* ...
* <ManyManyRelName>
* <ForeignClass id="ForeignID" href="LinkToForeignRecordInAPI" />
* <ForeignClass id="ForeignID" href="LinkToForeignRecordInAPI" />
* </ManyManyRelName>
* </ClassName>
*
* Access is controlled by two variables:
*
* - static $api_access must be set. This enables the API on a class by class basis
* - $obj->canView() must return true. This lets you implement record-level security
*/
protected function getHandler($className, $id) {
$obj = DataObject::get_by_id($className, $id);
if(!$obj) {
return $this->notFound();
}
if($obj->stat('api_access') && $obj->canView()) {
$xml = "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<$className>\n";
foreach($obj->db() as $fieldName => $fieldType) {
$xml .= "<$fieldName>" . Convert::raw2xml($obj->$fieldName) . "</$fieldName>\n";
}
foreach($obj->has_one() as $relName => $relObj) {
$fieldName = $relName . 'ID';
if($obj->$fieldName) {
$href = Director::absoluteURL(self::$api_base . "$relObj/" . $obj->$fieldName);
} else {
$href = Director::absoluteURL(self::$api_base . "$className/$id/$relName");
}
$xml .= "<$relName linktype=\"has_one\" href=\"$href\" id=\"{$obj->$fieldName}\" />\n";
}
foreach($obj->has_many() as $relName => $relObj) {
$xml .= "<$relName linktype=\"has_many\">\n";
$items = $obj->$relName();
foreach($items as $item) {
//$href = Director::absoluteURL(self::$api_base . "$className/$id/$relName/$item->ID");
$href = Director::absoluteURL(self::$api_base . "$relObj/$item->ID");
$xml .= "<$relObj href=\"$href\" id=\"{$item->ID}\" />\n";
}
$xml .= "</$relName>\n";
}
foreach($obj->many_many() as $relName => $relObj) {
$xml .= "<$relName linktype=\"many_many\">\n";
$items = $obj->$relName();
foreach($items as $item) {
//$href = Director::absoluteURL(self::$api_base . "$className/$id/$relName/$item->ID");
$href = Director::absoluteURL(self::$api_base . "$relObj/$item->ID");
$xml .= "<$relObj href=\"$href\" id=\"{$item->ID}\" />\n";
}
$xml .= "</$relName>\n";
}
$xml .= "</$className>";
$this->getResponse()->addHeader("Content-type", "text/xml");
return $xml;
} else {
return $this->permissionFailure();
}
}
/**
* Handler for object delete
*/
protected function deleteHandler($className, $id) {
if($id) {
$obj = DataObject::get_by_id($className, $id);
if($obj->stat('api_access') && $obj->canDelete()) {
$obj->delete();
} else {
return $this->permissionFailure();
}
}
}
/**
* Handler for object write
*/
protected function putHandler($className, $id) {
return $this->permissionFailure();
}
/**
* Handler for object append / method call
*/
protected function postHandler($className, $id) {
return $this->permissionFailure();
}
protected function permissionFailure() {
// return a 401
$this->getResponse()->setStatusCode(403);
return "You don't have access to this item through the API.";
}
protected function notFound() {
// return a 404
$this->getResponse()->setStatusCode(404);
return "That object wasn't found";
}
}

View File

@ -59,6 +59,13 @@ class DataObject extends ViewableData implements DataObjectInterface {
* @var string
*/
static $plural_name = null;
/**
* Allow API access to this object?
* @todo Define the options that can be set here
*/
static $api_access = false;
/**

View File

@ -128,6 +128,7 @@ Director::addRules(10, array(
'images/$Action/$Class/$ID/$Field' => 'Image_Uploader',
'' => 'RootURLController',
'sitemap.xml' => 'GoogleSitemap',
'api/v1/$ClassName/$ID' => 'RestfulServer',
));
Director::addRules(1, array(

View File

@ -0,0 +1,42 @@
<?php
class RestfulServerTest extends SapphireTest {
static $fixture_file = 'sapphire/tests/api/RestfulServerTest.yml';
function testCreate() {
// Test GET
$pageID = $this->idFromFixture('Page', 'page1');
$page1 = Director::test("api/v1/Page/$pageID", 'GET');
$page1xml = new RestfulService_Response($page1->getBody(), $page1->getStatusCode());
// Test fields
$this->assertEquals(200, $page1xml->getStatusCode());
$this->assertEquals('First Page', (string)$page1xml->xpath_one('/Page/Title'));
// Test has_many relationships
$comments = $page1xml->xpath('/Page/Comments/PageComment');
$this->assertEquals(Director::absoluteURL('api/v1/PageComment/3'), (string)$comments[0]['href']);
$this->assertEquals(Director::absoluteURL('api/v1/PageComment/4'), (string)$comments[1]['href']);
$this->assertEquals(3, (string)$comments[0]['id']);
$this->assertEquals(4, (string)$comments[1]['id']);
/// Test has_one relationships
$parent = $page1xml->xpath_one('/Page/Parent');
$this->assertEquals(Director::absoluteURL('api/v1/SiteTree/1'), (string)$parent['href']);
$this->assertEquals(1, (string)$parent['id']);
/*
$deletion = $service->get('Page/1', 'DELETE');
if($deletion->successfulStatus()) {
echo 'deleted';
} else {
switch($deletion->statusCode()) {
case 403: echo "You don't have permission to delete that object"; break;
default: echo "There was an error deleting"; break;
}
}
*/
}
}

View File

@ -0,0 +1,25 @@
PageComment:
comment1:
Name: Joe
Comment: This is a test comment
comment2:
Name: Jane
Comment: This is another test comment
comment3:
Name: Bob
Comment: Another comment
comment4:
Name: Bob
Comment: Second comment by Bob
Page:
home:
Title: Home
Comments: =>PageComment.comment1,=>PageComment.comment2
page1:
Title: First Page
Parent: =>Page.home
Content: <p>Some test content</p>
Comments: =>PageComment.comment3,=>PageComment.comment4
page2:
Title: Second Page