silverstripe-framework/api/RestfulServer.php

251 lines
8.4 KiB
PHP
Raw Normal View History

<?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)
*
* @package sapphire
* @subpackage api
*/
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();
}
// TO DO - inspect that Accept header as well. $_GET['accept'] can still be checked, as it's handy for debugging
$contentType = isset($_GET['accept']) ? $_GET['accept'] : 'text/xml';
if($obj->stat('api_access') && $obj->canView()) {
switch($contentType) {
case "text/xml":
$this->getResponse()->addHeader("Content-type", "text/xml");
return $this->dataObjectAsXML($obj);
case "text/json":
$this->getResponse()->addHeader("Content-type", "text/json");
return $this->dataObjectAsJSON($obj);
case "text/html":
case "application/xhtml+xml":
$this->getResponse()->addHeader("Content-type", "text/json");
return $this->dataObjectAsXHTML($obj);
}
} else {
return $this->permissionFailure();
}
}
/**
* Generate an XML representation of the given DataObject.
*/
protected function dataObjectAsXML(DataObject $obj) {
$className = $obj->class;
$id = $obj->ID;
$json = "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<$className>\n";
foreach($obj->db() as $fieldName => $fieldType) {
$json .= "<$fieldName>" . Convert::raw2xml($obj->$fieldName) . "</$fieldName>\n";
}
foreach($obj->has_one() as $relName => $relClass) {
$fieldName = $relName . 'ID';
if($obj->$fieldName) {
$href = Director::absoluteURL(self::$api_base . "$relClass/" . $obj->$fieldName);
} else {
$href = Director::absoluteURL(self::$api_base . "$className/$id/$relName");
}
$json .= "<$relName linktype=\"has_one\" href=\"$href\" id=\"{$obj->$fieldName}\" />\n";
}
foreach($obj->has_many() as $relName => $relClass) {
$json .= "<$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 . "$relClass/$item->ID");
$json .= "<$relClass href=\"$href\" id=\"{$item->ID}\" />\n";
}
$json .= "</$relName>\n";
}
foreach($obj->many_many() as $relName => $relClass) {
$json .= "<$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 . "$relClass/$item->ID");
$json .= "<$relClass href=\"$href\" id=\"{$item->ID}\" />\n";
}
$json .= "</$relName>\n";
}
$json .= "</$className>";
return $json;
}
/**
* Generate an XML representation of the given DataObject.
*/
protected function dataObjectAsJSON(DataObject $obj) {
$className = $obj->class;
$id = $obj->ID;
$json = "{\n className : \"$className\",\n";
foreach($obj->db() as $fieldName => $fieldType) {
$jsonParts[] = "$fieldName : \"" . Convert::raw2js($obj->$fieldName) . "\"";
}
foreach($obj->has_one() as $relName => $relClass) {
$fieldName = $relName . 'ID';
if($obj->$fieldName) {
$href = Director::absoluteURL(self::$api_base . "$relClass/" . $obj->$fieldName);
} else {
$href = Director::absoluteURL(self::$api_base . "$className/$id/$relName");
}
$jsonParts[] = "$relName : { className : \"$relClass\", href : \"$href\", id : \"{$obj->$fieldName}\" }";
}
foreach($obj->has_many() as $relName => $relClass) {
$jsonInnerParts = array();
$items = $obj->$relName();
foreach($items as $item) {
//$href = Director::absoluteURL(self::$api_base . "$className/$id/$relName/$item->ID");
$href = Director::absoluteURL(self::$api_base . "$relClass/$item->ID");
$jsonInnerParts[] = "{ className : \"$relClass\", href : \"$href\", id : \"{$obj->$fieldName}\" }";
}
$jsonParts[] = "$relName : [\n " . implode(",\n ", $jsonInnerParts) . " \n ]";
}
foreach($obj->many_many() as $relName => $relClass) {
$jsonInnerParts = array();
$items = $obj->$relName();
foreach($items as $item) {
//$href = Director::absoluteURL(self::$api_base . "$className/$id/$relName/$item->ID");
$href = Director::absoluteURL(self::$api_base . "$relClass/$item->ID");
$jsonInnerParts[] = " { className : \"$relClass\", href : \"$href\", id : \"{$obj->$fieldName}\" }";
}
$jsonParts[] = "$relName : [\n " . implode(",\n ", $jsonInnerParts) . "\n ]";
}
return "{\n " . implode(",\n ", $jsonParts) . "\n}";
}
/**
* 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";
}
}