RESTy - A RESTful Yii Extension

DESCRIPTION

RESTy enhances the Yii framework with extendible, configurable, and intuitive RESTful API support.

RESTful API is provided by the creation of subclasses of the RestController component. These subclasses reside in their own sub-directory within the normal controllers directory.

 e.g. controllers/api/ResourceController.php

HTTP requests to these controllers are then routed according to their HTTP request method. Specifically, to the controller method matching the naming convention REQUEST METHOD+CLASS METHOD().

Example REST Routing

The following are examples of this routing form (assume default REST controller directory 'api/'):

GET     example.com/index.php/api/user/              UserController->get();
GET     example.com/index.php/api/user?name=blah     UserController->get(); (with GET parameter name)
GET 	example.com/index.php/api/user/lookup        UserController->getLookup();
POST    example.com/index.php/api/user/              UserController->post();
DELETE  example.com/index.php/api/user/              UserController->delete();

HTTP Authentication

RESTy includes HTTP authentication support using the HTTP authentication framework. These are managed by the HTTP[auth type]Identity components.

The type of authentication accepted by a RestController subclass is determined by the RestController property 'accepted_auth_schemes'.

Client Authorizing using Basic

...Typical request headers...
Authorization: Basic [username:password encoded in base64]

Client Authorizing using Unencoded (not recommended, may corrupt header):

...Typical request headers...
Authorization: Unencoded username:password

General Tip

This extension, and its method of providing an API, results in another set of controllers to maintain. A simple way of reducing the development required to support both sets of controllers is to have your application models be as controller/implementation neutral as possible.

SETUP

1. Place source code into protected/extensions/

2. Insert the following lines into your main.php configuration file.

    <?php
      ...
      'import'  =>  array(
            'application.extensions.resty.components.*',
            'application.extensions.resty.models.*',
    ),
   
    'components'=>array(
            ...
            'urlManager'=>array(
                    ...
                    'urlFormat'=>'path',
                    'rules'=>array(
                            array( 'class'  =>'application.extensions.resty.components.RestUrlRule' ),
                    ...
                    ),
            ...
            ),
    ),
    ?>
   

3. Install the ApiUser table using the following command (make sure console config is setup to access your database):

    yiic  migrate  --migrationPath=application.extensions.resty.migrations
   

4. Create a sub-class of RestController, for your REST controllers to extends from, in protected/components/. Or, directly extend from RestController.

    Extending from custom RestController:
    class MyappRestController extends RestController{ ...
    class UserController extends MyappRestController{ ..
    	
    Extending directly:
    class UserController extends RestController{...
   

LICENSE

Copyright (c) 2012, Alem All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of the AlemCode nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL Alem BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.