RESTful API на Yii framework с RBAC и тестами

1. Одна из первых проблем с которой я столкнулся — сохранение различных сущностей в одной таблице. Для получения таких записей уже не достаточно просто указать имя модели как это предлагается, например тут. Один из примеров такого механизма — таблица AuthItems, которая используется фреймворком в механизме RBAC (если кто-то не знаком с ним — есть замечательная статья на эту тему). В ней содержатся роли, операции и задачи которые определяются флагом type, и для работы с этими сущностями через API мне хотелось использовать url не такого типа:
   

   GET: /api/authitems/?type=0 - получение списка операций
GET: /api/authitems/?type=1 - получение списка задач
GET: /api/authitems/?type=2 - получение списка ролей

   
   а такого:
   

   GET: /api/operations - получение списка операций
GET: /api/tasks - получение списка задач
GET: /api/roles - получение списка ролей
   

   
   Согласитесь, второй вариант выглядит очевиднее и понятнее, тем более для человека не знакомого с фрейморком и устройством RBAC в нем.
   
2. Вторая немаловажная возможность — механизм поиска и фильтрации данных, с возможностью задавать условия и комбинировать правила. Например, мне хотелось иметь возможность выполнить аналог такого запроса:
   

   SELECT * FROM users WHERE (age>25 AND first_name LIKE '%alex%') OR (last_name='shepard');
   

   
   
3. Порой не хватает возможности создания, обновления, удаления коллекций. Т.е. изменение n-ого количества записей одним запросом опять же используя поиск и фильтрацию. Например, зачастую требуется удалить или обновить все записи, попадающие под какое-либо условие, а использовать отдельные запросы слишком накладно.
   
4. Еще одним важным моментом была возможность получать связанные данные. Например: получить данные роли вместе со всеми её задачами и операциями.
   
5. Конечно невозможно хоть сколько-нибудь комфортно работать с API не имея возможности ограничить количество получаемых записей (limit), сместить начало выборки (offset), и указать порядок сортировки записей (order by). Так же не плохо бы иметь возможность группировки (group by).
   
6. Важно иметь возможность для каждой из операций проверять права пользователя (метод checkAccess все в том же RBAC).
   
7. Ну и наконец, все это дело нужно как-то тестировать.
   

Для начала о том, как API выглядит для клиента.

Получение записей

GET: /roles - список ролей
GET: /roles/42 - роль с id=42

Поиск и фильтрация

• <: меньне
• >: больше
• <=: меньне или равно
• >=: больше или равно
• <>: не равно
• =: равно

GET: /users?filter={"name":"alex"} — пользователи с именем alex
GET: /users?filter={"name":"alex", "age":">25"} — пользователи с именем alex И возрастом старше 25
GET: /users?filter=[{"name":"alex"}, {"name":"dmitry"}] — пользователи с именем alex ИЛИ dmitry
GET: /users?search={"name":"alex"} — пользователи с именем содержащим подстроку alex (alexey, alexander, alex и.т.д)

Работа со связанными данными

GET: /roles/42/operations — получить все операции принадлежащие роли с id = 42

Один ко многим

GET: operations?filter={"role_id":"42"} — получить все операции принадлежащие роли с id = 42

Многие ко многим

POST: /products/42/feature/1 — связать товар 42 с характеристикой товара 1
GET: /products/42/feature/1 — получить характеристику товара 1 (запись из таблицы features)

POST: /productfeatures — передав в теле запроса параметры product_id, feature_id, ordering и value мы свяжем характеристику и товар, указав значение и порядок сортировки.
GET: /productfeatures?filter={"product_id":"42"} — получим все связи товара с характеристиками. Ответ может выглядеть примерно так:

[
	{"id":"12","feature_id":"1","product_id":"42","value":"33"}, 
	{"id":"13","feature_id":"2","product_id":"42","value":"54"}
]

PUT: /productfeatures/12 — изменить связь с id=12

Получение связанных данных

GET: /productfeatures/12?with=product,feature — получение связи вместе с товаром и характеристиками. Пример ответа сервера:

{
	"id":"12",
	"feature_id":"1",
	"product_id":"42",
	"value":"33",
	"feature":{"id":"1","name":"Вес","unit":"кг"},
	"product":{"id":"42","name":"Стул", ...},
}

GET: /products/42?with=features — получение данных товара с id=42 и всех его характеристик в массиве. Пример ответа сервера:

{
	"id":"42",
	"name":"Стул",
	"features":[{"id":"1","name":"Вес","unit":"кг"}, {"id":"2","name":"Высота","unit":"см"}],
	...
}

{
	...,
	"status":1,
	"statuses":{0:"Нет в наличии", 1:"На складе", 2:"Под заказ"},
	...,
}

Удаление данных

DELETE: /role/42 - удалить роль с id=42
DELETE: /role - удалить все роли

DELETE: /role?filter={"name":"admin"} - удалить роли с именем "admin"

Создание данных

POST: /role - создать роль

[
	{"name":"admin"},
	{"name":"guest"}
]

Изменение данных

PUT: /role/42 - изменить запись 42

PUT: /role
передав в теле запроса

[
	{"id":"1","name":"admin"},
	{"id":"2","name":"guest"}
]

будут изменены записи с id 1 и 2.

PUT: /user?filter={"role":"guest"}' - изменить записи с role=guest

Лимит, смещение и порядок записей

GET: /users/?offset=10&limit=10
GET: /users/?order=id DESC
GET: /users/?order=id ASC

GET: /users/?order=parent_id ASC,ordering ASC

{
	data:[
		{id:1, name:"Alex", role:"admin"},
		{id:2, name:"Dmitry", role:"guest"}
	],
	meta:{
		total:2,
		offset:0,
		limit:10
	}
}

GET: roles?limit=5
Content-Range:items 0-4/10 - получены записи с 0 по 4, всего 10.

Content-Range:items 0-9/10 - получены записи с 0 по 9 всего 10.

Реализация на сервере.

    array('api/<controller>/list', 'pattern'=>'api/<controller:\w+>', 'verb'=>'GET'),
    array('api/<controller>/view', 'pattern'=>'api/<controller:\w+>/<id:\d+>', 'verb'=>'GET'),

    array('api/<controller>/create', 'pattern'=>'api/<controller:\w+>', 'verb'=>'POST'),

    array('api/<controller>/update', 'pattern'=>'api/<controller:\w+>/<id:\d+>', 'verb'=>'PUT'),
    array('api/<controller>/update', 'pattern'=>'api/<controller:\w+>', 'verb'=>'PUT'),

    array('api/<controller>/delete', 'pattern'=>'api/<controller:\w+>/<id:\d+>', 'verb'=>'DELETE'),
    array('api/<controller>/delete', 'pattern'=>'api/<controller:\w+>', 'verb'=>'DELETE'),

Контроллеры модуля API

actionView() — получение записи
actionList() — получение списка записей
actionCreate() — создание записи
actionUpdate() — изменение записи
actionDelete() — удаление записи

class RolesController extends ApiController
{   
    public function __construct($id, $module = null) {
        $this->model = new AuthItem('read'); 
        $this->baseCriteria = new CDbCriteria();
        $this->baseCriteria->addCondition('type='.AuthItem::ROLE_TYPE);
        parent::__construct($id, $module);
    }
    
    public function actionView(){
        if(!Yii::app()->user->checkAccess('getRole')){
            $this->accessDenied();
        }
        $this->getView();
    }

    public function actionList(){
        if(!Yii::app()->user->checkAccess('getRole')){
            $this->accessDenied();
        }
        $this->getList();
    }
    
    public function actionCreate(){
        if(!Yii::app()->user->checkAccess('createRole')){
            $this->accessDenied();
        }
        $this->model->setScenario('create');
        $this->priorityData = array('type'=>AuthItem::ROLE_TYPE);
        $this->create();
    }
    
    public function actionUpdate( ){
        if(!Yii::app()->user->checkAccess('updateRole')){
            $this->accessDenied();
        }
        $this->model->setScenario('update');
        $this->priorityData = array('type'=>AuthItem::ROLE_TYPE);
        $this->update();
    }
    
    public function actionDelete( ){
        if(!Yii::app()->user->checkAccess('deleteRole')){
            $this->accessDenied();
        }
        $this->model->setScenario('delete');
        $this->delete();
    }
    
    public function getRelations() {
        return array(
            'roleoperations'=>array(
                'relationName'=>'operations',
                'columnName'=>'operations',
                'return'=>'array'
            )
        );
    }
}

{
    bizrule: null
    description: "Administrator"
    id: "1"
    name: "admin"
    operations: [{...}, {...},...]
    type: "2"
}

<?php
class TagController extends ApiController
{
    public function __construct($id, $module = null) {
        $this->model = new Tag('read'); 
        parent::__construct($id, $module);
    }
    
    public function actionView(){
        $this->getView();
    }
    
    public function actionList(){
        $this->getList();
    }
    
    public function actionCreate(){
        if(!Yii::app()->user->checkAccess('createTag')){
            $this->accessDenied();
        }
        $this->create();
    }
    
    public function actionUpdate(){
        if(!Yii::app()->user->checkAccess('updateTag')){
            $this->accessDenied();
        }
        $this->update();
    }
    
    public function actionDelete(){
        if(!Yii::app()->user->checkAccess('deleteTag')){
            $this->accessDenied();
        }
        $this->delete();
    }
}

array(
    'limit' => 100, 
    'offset' => 0, 
    'order' => 'id ASC'
)

array(
    'total'=>10,
    'start'=>6,
    'end'=>15
)

• getView()
  Выполняет поиск записи в соответствии с GET параметрами. Возвращает массив параметров записи или отправляет данные пользователю. В случае если запись не найдена — отправляет пользователю сообщение об ошибке с кодом ответа 404 или возвращает массив с соответствующей информацией об ошибке. Устанавливает свойство statusCode в соответствующее значение после выполнения запроса.
  

  getView(boolean $sendToEndUser = true, integer $id)
  $sendToEndUser	boolean	Отправлять ли данные пользователю после завершения операции или же вернуть результат действия в виде массива.
  $id	integer	Параметр id записи. Если не передан — заполняется из GET параметров.

  
  
• getList()
  Выполняет поиск записей в соответствии с GET параметрами. Возвращает массив найденных записей или пустой массив.
  

  getList(boolean $sendToEndUser = true)
  $sendToEndUser	boolean	Отправлять ли данные пользователю после завершения операции или же вернуть результат действия в виде массива.

  
  
• create()
  Создает новую запись с данными полученными из тела запроса. В случае если в теле запроса передан массив атрибутов — будет сознано соответствующее количество записей. Возвращает массив с атрибутами новой записи.
  Например:
  

  array(
      'name'=>'Alex',
      'age'=>'25'
  ) //будет создана запись с соотв. параметрами
  

  
  

  array(    
      array(
          'name'=>'Alex',
          'age'=>'25'
      ),
      array(
          'name'=>'Dmitry',
          'age'=>'33'
      )
  ) //будет создана коллекция записей с соотв. параметрами
  

  
  

  create(boolean $sendToEndUser = true)
  $sendToEndUser	boolean	Отправлять ли данные пользователю после завершения операции или же вернуть результат действия в виде массива.

  
  
• update()
  Обновляет запись, найденную в соответствии с полученными GET параметрами. Возвращает массив параметров записи или отправляет данные пользователю. В случае если запись не найдена — отправляет пользователю сообщение об ошибке с кодом ответа 404 или возвращает массив с соответствующей информацией об ошибке. В случае если в теле запроса передан массив записей — будет изменено соответствующее количество записей и возвращен массив с их значениями.
  Например:
  

  PUT: users/1

  
  

  array(
      'name'=>'Alex',
      'age'=>'25'
  ) //будет изменена запись найденная в соответствии с полученными GET параметрами
  

  
  

  PUT: users

  
  

  array(    
      array(
          'id'=>1,
          'name'=>'Alex',
          'age'=>'25'
      ),
      array(
          'id'=>2,
          'name'=>'Dmitry',
          'age'=>'33'
      )
  ) //будет изменена коллекция записей с соотв с параметром id переданным для каждой из них. Номер записи не передается в url
  

  
  

  update(boolean $sendToEndUser = true, integer $id)
  $sendToEndUser	boolean	Отправлять ли данные пользователю после завершения операции или же вернуть результат действия в виде массива.
  $id	integer	Параметр id записи. Если не передан — заполняется из GET параметров.

  
  
• delete()
  Удаляет запись, найденную в соответствии с полученными GET параметрами. Возвращает массив параметров удаленной записи или отправляет данные пользователю. В случае если запись не найдена — отправляет пользователю сообщение об ошибке с кодом ответа 404 или возвращает массив с соответствующей информацией об ошибке. Если не получен параметр id — будут удалены все записи.
  

  delete(boolean $sendToEndUser = true, integer $id)
  $sendToEndUser	boolean	Отправлять ли данные пользователю после завершения операции или же вернуть результат действия в виде массива.
  $id	integer	Параметр id записи. Если не передан — заполняется из GET параметров.

  
  

Тестирование

...
'proddb'=>array(
        'class'=>'CDbConnection',
        'connectionString' => 'mysql:host=localhost;dbname=yiirestmodel',
        'emulatePrepare' => true,
        'username' => '',
        'password' => '',
        'charset' => 'utf8',
), //коннект к рабочей базе
'db'=>array(
        'connectionString' => 'mysql:host=localhost;dbname=yiirestmodel-test',
), //коннект к тестовой базе
'authManager'=>array(
        'connectionID'=>'proddb', //использовать рабочую базу
),
...

class UsersControllerTest extends ApiTestCase
{
    public $fixtures = array(
        'users'=>'User'
    );

    public function testActionView(){
        $user = $this->users('admin');
        
        $response = $this->get('api/users/'.$user->id, array(), array('cookies'=>$this->getAuthCookies()));
        
        $this->assertEquals($response['code'], 200);
        $this->assertNotNull($response['decoded']);
        $this->assertEquals($response['decoded']['id'], $user->id);
        $this->assertArrayNotHasKey('password', $response['decoded']);
        $this->assertArrayNotHasKey('guid', $response['decoded']);
    }
    
    public function testActionList(){
        $response = $this->get('api/users', array(), array('cookies'=>$this->getAuthCookies()));
        $this->assertEquals($response['code'], 200);
        $this->assertEquals(count($response['decoded']), User::model()->count());
    }
    
    public function testActionCreate(){
        $response = $this->post(
            'api/users',
            array(
                'first_name' => 'new_first_name',
                'middle_name' => 'new_middle_name',
                'last_name' => 'new_last_name',
                'password' => 'new_user_psw',
                'password_repeat' => 'new_user_psw',
                'role' => 'guest',
            ),    
            array('cookies'=>$this->getAuthCookies())
        );
        
        $this->assertEquals($response['code'], 200);
        $this->assertNotNull($response['decoded']);
        $this->assertArrayHasKey('id', $response['decoded']);
        $this->assertArrayNotHasKey('password', $response['decoded']);
        $this->assertNotNull( User::model()->findByPk($response['decoded']['id']) );
    }
}

public $loginUrl = 'api/login';
public $loginData = array('login'=>'admin', 'password'=>'admin');

array(
    'Date' => "Fri, 23 May 2014 12:10:37 GMT"
    'Server' =>"Apache/2.4.7 (Win32) OpenSSL/1.0.1e PHP/5.5.9"
    ...
)

array('login'=>'admin', 'password'=>'admin');

• getAuthCookies()
  Выполняет запрос авторизации.
  

  getAuthCookies(boolean $reload = false)
  $reload	boolean	Выполнять ли запрос при повторном вызове или вернуть значение полученное при первом вызове.

  
  
• get()
  Выполняет запрос методом GET. Возвращает массив с параметрами ответа сервера.
  

  get( string $url, array $params = array(), array $options = array()){
  $url	string	Url адрес для выполнения запроса
  $params	array	Массив GET параметров запроса
  $options	array	Опции запроса, которые будут подставлены в метод curl_setopt_array. Также в массиве может присутствовать элемент cookies, значением которого должен быть массив (имя=>значение) кук для отправки их в заголовках запроса.

  
  
• post()
  Выполняет запрос методом POST. Возвращает массив с параметрами ответа сервера.
  

  post( string $url, array $params = array(), array $options = array()){
  $url	string	Url адрес для выполнения запроса
  $params	array	Массив параметров запроса передаваемых в теле запроса
  $options	array	Опции запроса, которые будут подставлены в метод curl_setopt_array. Также в массиве может присутствовать элемент cookies, значением которого должен быть массив (имя=>значение) кук для отправки их в заголовках запроса.

  
  
• put()
  Выполняет запрос методом PUT. Возвращает массив с параметрами ответа сервера.
  Описание параметров см. ApiTestCase::post()
  
• delete()
  Выполняет запрос методом DELETE. Возвращает массив с параметрами ответа сервера.
  Описание параметров см. ApiTestCase::post()
  

Заключение

P.S.