Towards RESTful PHP - 5 Basic Tips
What is REST?
REST is an architectural style, or set of conventions, for web applications and services that centers itself around resource manipulation and the HTTP spec. Web apps have traditionally ignored the HTTP spec and moved forward using a subset of the protocol: GET and POST, 200 OKs and 404 NOT FOUNDs. As we entered a programmable web of applications with APIs the decision to ignore HTTP gave us problems we're still dealing with today. We have an internet full of applications with different interfaces (GET /user/1/delete vs. POST /user/delete {id=1}). With REST we can say /user/1 is a resource and use the HTTP DELETE verb to delete it. For more detail on REST check out wikipedia and "quick pitch".
Tip #1 Using PUT and DELETE methods
In PHP you can determine which HTTP method was used with: $_SERVER['REQUEST_METHOD']; From web browsers this will be either GET or POST. For RESTful clients applications need to support PUT and DELETE (and ideally OPTIONS, etc.) as well. Unfortunately PHP doesn't have $_PUT and $_DELETE variables like it does $_POST and $_GET. Here's how to access the content of a PUT request in PHP:
$_PUT = array();
if($_SERVER['REQUEST_METHOD'] == 'PUT') {
$putdata = file_get_contents('php://input');
$exploded = explode('&', $putdata);
foreach($exploded as $pair) {
$item = explode('=', $pair);
if(count($item) == 2) {
$_PUT[urldecode($item[0])] = urldecode($item[1]);
}
}
}
Tip #2: Send Custom HTTP/1.1 Headers
PHP's header function allows custom HTTP headers to be sent to the client. The HTTP/1.x header contains the response code from the server. PHP will, by default, send back a 200 OK status code which suggests that the request has succeeded even if it has die()'ed or a new resource has been created. There are two ways to change the status code of your response:
header('HTTP/1.1 404 Not Found');
/* OR */
header('Location: http://www.foo.com/bar', true, 201); // 201 CREATED
The first line is a generic way of setting the response status code. If your response requires another header, like the Location header to the resource of a '201 Created' or '301 Moved Permanently', placing the integer status code in the third parameter of header is a shortcut. It is the logical equivalent of the following example, which is easier to read at the cost of being an extra line of code.
header('HTTP/1.1 201 Created');
header('Location: http://www.foo.com/bar');
Tip #3: Send Meaningful HTTP Headers
Policy for deciding when it is appropriate to send each HTTP status code is a full post on its own and the HTTP spec leaves room for ambiguity. There are many other resources on the net which provide insights so I'll just touch on a few.
201 Created
Used when a new resource has been created. It should include a Location header which specifies the URL for the resource (i.e. books/1). The inclusion of a location header does not automatically forward the client to the resource, rather, 201 Created responses should include an entity (message body) which lists the location of the resource.
202 Accepted
Allows the server to tell the client "yeah, we heard your order, we'll get to it soon." Think the Twitter API on a busy day. Where 202 Created implies the resource has been created before a response returns, 202 Accepted implies the request is ok and in a queue somewhere.
304 Not Modified
Used in conjunction with caching and conditional GET requests (requests with If-Modified-Since / If-None-Match headers) allows web applications to say "the content hasn't changed, continue using the cached version" without having to re-render and send the cached content down the pipe.
401 Unauthorized
Used when attempting to access a resource which requires authentication credentials the request does not carry. This is used in conjunction with www-authentication.
500 Internal Server Error
Better than OK when your PHP script dies or reaches an exception. Informs the other end that the problem was on the server side and avoids potential for caching the response.
Tip #4: Don't Use $_SESSION
A truly RESTful PHP application should be entirely stateless- all requests should contain enough information to be handled without additional server side state. In practice this means storing authentication information in a cookie with a timestamp and a checksum. Additional data can also be stored in a cookie. In the event you need more than a cookie's worth of data fall back to storing it in a central database with the authentication still in the cookie. This is how Flickr approaches statelessness.
Tip #5: Test with cURL or rest-client
cURL makes it easy to execute any HTTP METHOD on a resource URL. You can pass request parameters and headers as well as inspect response headers and data. The command line tool 'curl' is standard on many *nix distros. Windows users should check out MinGW/MSYS which supports cURL. Even PHP has cURL functions which are enabled on most hosts (php/curl install page). cURL Example Usage & Common Parameters:
curl -X PUT \
http://www.foo.com/bar/1 \
-d "some=var" \
-d "other=var2" \
-H "Accept: text/json" \
-I
-X [METHOD] Specify the HTTP method. -d "name=value" Set a POST/PUT field name and value. -H [HEADER] Set a header. -I Only display response's headers.
Tip #6 - Use a RESTful PHP Framework
Frankly, developers shouldn't have to worry about many of these low-level details of REST when writing PHP apps. REST is based on conventions and conventions, by nature, involve a lot of boilerplate. This is right up a framework's alley (as Rails has shown). What options exist for PHP? CodeIgniter's routing completely ignores the HTTP METHOD so there is serious hacking that needs to be done. Cake has REST support but wasn't designed to make specifying useful response status codes a part of the framework. Konstruct appears to have a very well thought out architecture for a controllers framework built around HTTP and REST. Unfortunately it is not easily approached and lacking (intentionally) many components, like an ORM layer, developers have come to expect in a modern web framework.
(Disclaimer: Shameless Plug!) The lack of a solid, RESTful PHP framework was one of my primary motivations for creating the Recess! Framework. Recess is a full-stack, open source (MIT), RESTful PHP framework. If you're interested in writing RESTful PHP applications check it out and sign-up to be notified of its upcoming release.