Welcome to the Cookbook

The fastest way to get up and running with REST is to add a few lines to your routes.php file, found in app/config. The Router object features a method called mapResources(), that is used to set up a number of default routes for REST access to your controllers. If we wanted to allow REST access to a recipe database, we'd do something like this:

//In app/config/routes.php...
	
Router::mapResources('recipes');
Router::parseExtensions();

1. //In app/config/routes.php...
3. Router::mapResources('recipes');
4. Router::parseExtensions();

The first line sets up a number of default routes for easy REST access. These routes are HTTP Request Method sensitive.

HTTP Method	URL	Controller action invoked
GET	/recipes	RecipesController::index()
GET	/recipes/123	RecipesController::view(123)
POST	/recipes	RecipesController::add()
POST	/recipes/123	RecipesController::edit(123)
PUT	/recipes/123	RecipesController::edit(123)
DELETE	/recipes/123	RecipesController::delete(123)

CakePHP's Router class uses a number of different indicators to detect the HTTP method being used. Here they are in order of preference:

1. The _method POST variable
2. The X_HTTP_METHOD_OVERRIDE
3. The REQUEST_METHOD header

The _method POST variable is helpful in using a browser as a REST client (or anything else that can do POST easily). Just set the value of _method to the name of the HTTP request method you wish to emulate.

Once the router has been set up to map REST requests to certain controller actions, we can move on to creating the logic in our controller actions. A basic controller might look something like this:

// controllers/recipes_controller.php

class RecipesController extends AppController {

	var $components = array('RequestHandler');

	function index() {
    	$recipes = $this->Recipe->find('all');
    	$this->set(compact('recipes'));
	}

	function view($id) {
		$recipe = $this->Recipe->findById($id);
		$this->set(compact('recipe'));
	}

	function edit($id) {
		$this->Recipe->id = $id;
		if ($this->Recipe->save($this->data)) {
			$message = 'Saved';
		} else {
			$message = 'Error';
		}
		$this->set(compact("message"));
  	}

	function delete($id) {
		if($this->Recipe->delete($id)) {
			$message = 'Deleted';
		} else {
			$message = 'Error';
		}
		$this->set(compact("message"));
	}
}

1. // controllers/recipes_controller.php
2. class RecipesController extends AppController {
3. var $components = array('RequestHandler');
4. function index() {
5. $recipes = $this->Recipe->find('all');
6. $this->set(compact('recipes'));
7. }
8. function view($id) {
9. $recipe = $this->Recipe->findById($id);
10. $this->set(compact('recipe'));
11. }
12. function edit($id) {
13. $this->Recipe->id = $id;
14. if ($this->Recipe->save($this->data)) {
15. $message = 'Saved';
16. } else {
17. $message = 'Error';
18. }
19. $this->set(compact("message"));
20. }
21. function delete($id) {
22. if($this->Recipe->delete($id)) {
23. $message = 'Deleted';
24. } else {
25. $message = 'Error';
26. }
27. $this->set(compact("message"));
28. }
29. }

Since we've added a call to Router::parseExtensions(), the CakePHP router is already primed to serve up different views based on different kinds of requests. Since we're dealing with REST requests, the view type is XML. We place the REST views for our RecipesController inside app/views/xml. We can also use the XmlHelper for quick-and-easy XML output in those views. Here's what our index view might look like:

// app/views/recipes/xml/index.ctp

<recipes>
	<?php echo $xml->serialize($recipes); ?>
</recipes>

1. // app/views/recipes/xml/index.ctp
2. <recipes>
3. <?php echo $xml->serialize($recipes); ?>
4. </recipes>

Experienced CakePHP users might notice that we haven't included the XmlHelper in our RecipesController $helpers array. This is on purpose - when serving up a specific content type using parseExtensions(), CakePHP automatically looks for a view helper that matches the type. Since we're using XML as the content type, the XmlHelper is automatically loaded up for our use in those views.

The rendered XML will end up looking something like this:

<posts>
	<post id="234" created="2008-06-13" modified="2008-06-14">
		<author id="23423" first_name="Billy" last_name="Bob"></author>
		<comment id="245" body="This is a comment for this post."></comment>
	</post>	
	<post id="3247" created="2008-06-15" modified="2008-06-15">
		<author id="625" first_name="Nate" last_name="Johnson"></author>
		<comment id="654" body="This is a comment for this post."></comment>
	</post>
</posts>

1. <posts>
2. <post id="234" created="2008-06-13" modified="2008-06-14">
3. <author id="23423" first_name="Billy" last_name="Bob"></author>
4. <comment id="245" body="This is a comment for this post."></comment>
5. </post>
6. <post id="3247" created="2008-06-15" modified="2008-06-15">
7. <author id="625" first_name="Nate" last_name="Johnson"></author>
8. <comment id="654" body="This is a comment for this post."></comment>
9. </post>
10. </posts>

Creating the logic for the edit action is a bit trickier, but not by much. Since you're providing an API that outputs XML, it's a natural choice to receive XML as input. Not to worry, however: the RequestHandler and Router classes make things much easier. If a POST or PUT request has an XML content-type, then the input is taken and passed to an instance of Cake's Xml object, which is assigned to the $data property of the controller. Because of this feature, handling XML and POST data in parallel is seamless: no changes are required to the controller or model code. Everything you need should end up in $this->data.