knudpotente
commented
12 years ago Below is the complete code for the sub-class I'm currently designing to use as a super for my RESTful controllers. It implements standard RESTful practices, and the behaviour can be easily overridden by sub-classes, if needed:
<?php
class Controller_Restful extends Controller_Rest
{
public function router($res, array $args)
{
parent::router($res, $args);
switch (Input::method()){
case "GET":
$this->get_index($res,$args);
break;
case "POST":
$this->post_index($res,$args);
break;
case "PUT":
$this->put_index($res,$args);
break;
case "DELETE":
$this->delete_index($res,$args);
break;
default:
// The request uses an unsupported http method
// Handle the error here - i.e.:
$data['error'] = "Unsupported HTTP method request.";
$this->response->set_header('Allow', 'GET, POST, PUT, DELETE');
$this->response($data, 405);
}
}
// HTTP Status Codes that MUST be used when producing Responses for
// our GET, POST, PUT and DELETE operations:
// 200 - Success - operation successfull, return resource info as $data
// 204 - No Content - operation successfull, but no $data will be returned.
// 400 - Bad Request - operation could not be done, because resource info
// was malformed (or missing). No return $data needed.
// 403 - Forbidden - client does not have authorisation to perform the
// operation at this URI. May return $data explaining.
// 404 - Not Found - resource at this URI does not exist. No $data returned.
// 500 - Internal Server Error - operation produces an error - such as a
// database query error. May return $data explaining.
//
// Responses WITH $data can be set with:
// $this->response($data,$http_status);
//
// Responses WITHOUT $data can be set simply with:
// $this->response->status = $http_status;
public function get_index($res, array $args)
{
}
public function post_index($res, array $args)
{
}
public function put_index($res, array $args)
{
// If PUTing without specifying a resource, then
// client is attempting to update an entire list of resources at once.
// This is usually a security risk and in most cases not to be allowed:
if (empty($res)){
$data['error'] = "Unsupported HTTP method request.";
$this->response->set_header('Allow', 'GET, POST');
$this->response($data, 405);
}
}
public function delete_index($res, array $args)
{
// If DELETEing without specifying a resource, then
// client is attempting to delete an entire list of resources at once.
// This is usually a security risk and in most cases not to be allowed:
if (empty($res)){
$data['error'] = "Unsupported HTTP method request.";
$this->response->set_header('Allow', 'GET, POST');
$this->response($data, 405);
}
}
}
dhrrgn
philsturgeon
In a RESTful API, the URI should identify only the resource that is being acted on - for instance:
In order to identify the action that is to be performed with these resources, in a RESTful API we use only the HTTP verb:
As can be seen, in a RESTful API the action is NOT specified in the URI - this is a very important distinction between RESTful and non-RESTful APIs. The following, for instance, is not a RESTful URI:
Because this URI specifies an action, not a resource.
In a RESTful interface, we should only ever have to deal with 4 actions, and a RESTful controller, therefore, should only need to have 4 functions: get(), post(), put() and delete().
In 1.1-RC1, however, the 'standard' Controller_Rest seems to rely on the programmer having to use action-based URIs in order to route to an appropriate function. Even though it's a 'REST Controller', it is not using the HTTP method to determine what action to take on the resource. This seems to be teaching and promoting un-RESTful implementations.
It is reasonably trivial to implement 'standard' RESTful routing, simply by adding the following router() function at the beginning of a Controller_Rest sub-class:
The controller then has to implement the appropriate _get_index(), post_index(), put_index() and deleteindex() functions.
It seems to me, that this should be the default behaviour and setup of a Controller_Rest class. If the programmer needs to implement action-based URIs, then they are diverging from the RESTful standard, and they should have to use router() - and not the other way around.