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

api/RestfulServer.php

@@ -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";
+	}
+	
+}

core/model/DataObject.php

@@ -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;
 
 
 	/**

main.php

@@ -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(

tests/api/RestfulServerTest.php

@@ -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;
+			}
+		}
+		*/
+
+	}
+}

tests/api/RestfulServerTest.yml

@@ -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