Rest Controller

What is a Rest controller?

A Rest Controller is an extension of the Base Controller which has RESTful support built in. This will allow you to build API's with ease.

Please note: if you have a before() or router method in your REST controller extension you must call the parent method parent::before() (or router) for it to keep working properly.

Using the Rest controller

Like all Controllers, you create a class in the fuel/app/classes/controller directory. They need to extend the Controller_Rest class and are prefixed by default by "Controller_". Below is an example of the controller "test":

class Controller_Test extends Controller_Rest
{

	public function get_list()
	{
		return $this->response(array(
			'foo' => Input::get('foo'),
			'baz' => array(
				1, 50, 219
			),
			'empty' => null
		));
	}
}

This controller method "list" is called by the following URL:

http://localhost/test/list.json?foo=bar

You'll notice that instead of the usual "action_" prefix the Rest Controller uses the HTTP method as a prefix. When no function the corresponding HTTP method prefix is found it will fall back to the "action_" prefix. The HTTP methods that Rest Controller supports are the following:

XML Base Node Name

When using XML output you can set the XML basenode by setting the $xml_basenode param.

class Controller_Test extends Controller_Rest
{
	// Set it for the whole controller
	protected $xml_basenode = 'my_basenode';

	// Or inside your controller function
	public function get_items()
	{
		$this->xml_basenode = 'other_basenode';

		return $this->response(array(
			'foo' => Input::get('foo'),
			'baz' => array(
				1, 50, 219
			),
			'empty' => null
		));
	}
}

You can also set the XML basenode app-globally by changing the rest.xml_basenode config setting.

HTTP Method Description
GET Used to fetch information about an existing resource. This is used by browsers when you enter a URL and hit go, or when you click on a link, so it perfect for fetching information on one of your REST resources (like user).
POST Used to update an existing resource with information. Browsers use this to submit most types of forms on the Internet, although some use GET as well by submitting the form action with a query string containing the field data.
PUT Less commonly used and not supported by most browsers, PUT is used to create a new resource.
DELETE Also not used by many browsers, this HTTP verb rather obviously is used to delete a resource.

Output

{
	"foo":"bar",
	"baz":[1,50,219],
	"empty":null
}

This is output as json because a file extension was defined in the URL. By default, responses will be formatted as XML or whichever format is set in fuel/core/config/rest.php.

Supported Formats

Format determination

To determine the format in which the result should be returned, the REST controller uses the following algorithm:

Special controller methods

response($data = array(), $http_code = 200)

This method is used to send your response data through the formatting and output logic. You can optionally set a status code as the 2nd parameter.