Class: Restful

Restful is a base class for implementing REST APIs. Restful is meant to be extended and passed to Controller::restful() to create RESTful request handlers. Works with GET, POST, PUT, and DELETE request methods, as well as the X-HTTP-Method-Override header if your server can't handle PUT and DELETE requests.

Usage:

1. Create a Restful-based class and save it to the file apps/myapp/lib/API.php:

<?php

namespace myapp;

class API extends \Restful {
    // Accessible via `GET /myapp/api/article/123`
    public function get_article ($id) {
        // Return some data
        return (object) array (
            'id' => $id,
            'title' => 'My title'
        );
    }

    // Accessible via `POST /myapp/api/article`
    public function post_article () {
        // Return an error
        return $this->error ('Error message');
    }
}

?>

2. Create a handler and assign your class as its restful handler in the file apps/myapp/handlers/api.php:

<?php

$this->restful (new myapp\API);

?>

Responses come in the following form, depending on success or failure:

{"success": true, "data": {"id": 123, "title": "My title"}}

{"success": false, "error": "Error message"}

Additional notes:

  • Parameters passed to methods requests are expected to be from the extra URL parameters. $_GET and $_POST are available separately.

  • PUT data can be accessed via $this->get_put_data() or via $this->get_put_data (true) to automatically JSON decode it.

Properties

public $controller

The controller object.

public $cache

The cache object.

public $wrap = true

Whether wrap() should alter the output data to add a {"success":true,"data":"..."} structure around it.

public $suppress_output = false

Whether to suppress error logs and echo statements, primarily for unit testing.

public $custom_routes = array ()

List any custom routes in this array. Useful for complex routes such as with nested resources. Format is as follows:

public $custom_routes = array (
    'GET article/%d/comment/%d' => 'article_comment'
);

The key is made up of the request method and the route pattern to match. The value is the name of the method that handles the request.

The request method can be specified as follows:

  • One of GET, POST, etc.
  • Multiple methods combined via GET|POST
  • All methods via ALL

The route pattern matches the tail of the request URI after the current handler's name. For example, if your REST handler is found at /myapp/api and you want to match GET /myapp/api/custom/method then you would specify:

'GET custom/method' => 'custom_method'

Pattern matching in the route works with %s for matching strings and %d for matching numbers, which is converted into a regular expression for evaluation. For example:

'GET article/%d/comment/%d' => 'article_comment'

Where article_comment() should accept two parameters:

public function article_comment ($article_id, $comment_id) {
    // etc.
}

Methods

public get_params ($params)

Get the specified parameters from the PUT request data. Wraps get_put_data(true) with additional capabilities to more easily validate input.

If provided with a list of parameters, it will return only the parameters specified. If the expected parameter list is provided as an associative array, its keys will be the parameter names and the values will either be true for required fields, false for optional fields, or an associative array of input validations that will be passed to Validator::validate_list().

Validation rules can be mixed and matched, so you can specify one field optional with a false boolean and another with a set of validation rules.

public get_put_data ($decode = false)

Get and optionally JSON decode the PUT requests data.

public get_raw_post_data ($decode = false)

Get and optionally JSON decode the raw POST data.

public wrap ($data)

Wrap the specified data in a {success:true,data:data} structure and echo it.

public error ($message, $code)

Echo a JSON-encoded error response object and return null.

public require_acl ($resource)

Verify that the user is authorized to access one or more resources. If the user is not logged in, it will also return false.