Компонент API

Для организации внешнего доступа к базе данных программными средствами был разработан данный компонент.

Компонент позволяет организовать доступ к БД через зарегистрированные в системе мапперы. В основе компонента лежат технологи REST/CRUD.

REST (сокр. от англ. Representational State Transfer — «передача репрезентативного состояния») - метод взаимодействия компонентов распределённого приложения в сети Интернет, при котором вызов удаленной процедуры представляет собой обычный HTTP-запрос (обычно GET или POST; такой запрос называют REST-запрос), а необходимые данные передаются в качестве параметров запроса.

CRUD (create, read, update, delete — «создание, чтение, обновление, удаление») - сокращённое именование 4-х базовых функций, используемых при работе с персистентными хранилищами данных.

Применение

Компонент прозрачно вызывает методы мапперов при обращении по определенным адресам.

Так как компонент следует технологии CRUD, то при обработке учитывает тип запроса. Т.е при обращении по одному и тому же адресу, но разными типами запросов (GET, POST, PUT, DELETE) будут производиться разные действия.

Авторизация

В компоненте производится basic-авторизация по принципу закрытых зон (realms) По умолчанию используется закрытая зона с именем api (это можно изменить в настройках компонента). Т.е. в конфигурационном файле необходимо завести новую зону с именем api_realm.

// app/config/site.php
->api_realm
    	->auth_url('http://site.ru')
    	->passwords(array(
		'login:pass',
	))
->end

Более подробную информацию можно получить в статье Админка и закрытые зоны.

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

Общий вид адреса для получения списка записей имеет следующий вид:

/api/MapperName/[MethodName1, [/MethodName2, ...]]

Например, для получения списка записей маппера my_mapper необходимо обратиться GET-запросом по адресу /api/mapper_name/, в ответ будет возвращен список всех записей маппера (результатом выборки будет результат, возвращенный CMS::orm()->mapper_name()->select();).

Так же можно вызывать различные map_ - методы маппера, для этого в адрес необходимо добавить название этого метода. Например, /api/my_mapper/list/, в этом случае ответ будет содержать результат работы метода map_list().

Количество вызываемых методов в запросе не ограничено, т.е. вызов следующих методов будет происходить в порядке их следования в адресе.

Добавление записи

Для того чтобы добавить запись в таблицу необходимо сформировать POST-запрос по адресу маппера (например, /api/my_mapper/), в котором передать данные записи.

Всю валидацию переданных данных необходимо производить в методах before_insert() или before_save() класса сущности . в случае корректных данных этот метод должен вернуть true, в противном случае добавление записи прервется и в ответ будет возвращена ошибка.

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

Общий вид адреса одной записи имеет следующий вид:

/api/MapperName/RecordID/

где:

• MapperName - имя маппера.
• RecordID - числовой идентификатор записи в таблице.

В этом случае компонент произведет вызов метода find() у маппера, и в случае положительного результата вернет данные записи.

Обновление

Для того чтобы обновить запись в таблице, необходимо отправить PUT-запрос на адрес одной записи (например, /api/my_mapper/1/), в котором передать новые значения.

Всю валидацию переданных данных необходимо производить в методах before_update() или before_save() класса сущности, в случае корректных данных этот метод должен вернуть true, в противном случае добавление записи прервется и в ответ будет возвращена ошибка.

Удаление

Для удаления записи необходимо сформировать DELETE-запрос по адресу одной записи (например, /api/my_mapper/1/).

Формат ответа

По умолчанию компонент формирует ответ в json-формате. В общем случае ответ имеет следующую структуру:

{
    "success": true, // флаг успешности запроса
    "total": 36,     // кол-во записей в ответе
    "data": []       // данные ответа
}

В зависимости от вида запроса в поле data может содержаться как массив записей (при запросе списка), так и единичный объект.

Управление результатом

Компонент позволяет управлять данными в ответе с помощью определенных GET-параметров.

Настройка набора полей

По умолчанию при формировании ответа компонент будет использовать все поля записи, определенные в схеме маппера.

Но, как правило, необходимо либо добавить какие-то недостающие поля, либо наоборот, ограничить набор возвращаемых данных.

Для того, чтобы настроить набор возвращаемых полей записи, необходимо переопределить метод __attrs($flavor = ''). Данный метод должен сформировать массив имен полей, которые необходимо будет вернуть в ответе.

На вход метод принимает один параметр, если при запросе в адрес добавить GET-параметр с именем flavor, то значение этого параметра будет передано в метод. На основе значений этого параметра можно формировать различные наборы полей.

Так же, если необходимо ограничить выборку несколькими полями, в адрес можно добавить еще один GET-параметр columns, в котором необходимо перечислить имена колонок, через запятую, которые необходимо вернуть. В этом случае при запросе данных из БД будут выбраны только указанные поля.

Ограничение количества

По умолчанию, при выборе списка компонент ограничивает количество записей в результате - 20. Для того чтобы управлять количеством строк в результате нужно использовать следующие GET-параметры:

• limit - отвечает за количество строк в результате.
• offset - отвечает за смещение при выборе.

Данные параметры используются при формировании запроса к БД в части LIMIT выражения.

Фильтрация данных

Для фильтрации результата в адресе необходимо определить параметр filter. Значением этого параметра должен быть преобразованный массив следующего вида:

[{
    field: '',
    data: {
        value: '',
        comparison: '',
        type: ''
    }
},{
    ...
}]

где:

• field - имя поля для фильтрации.
• data.value - сравниваемое значение.
• data.comparison - вид сравнения (может принимать значения: eq => =, lt => <, gt => >, not => !=). Не нужно указывать если используется data.type
• data.type - имя фильтра, в компоненте реализованы следующие фильтры:
• string - будет формировать LIKE запрос.
• list - в запросе будет использован оператор IN.
• not_list - в запросе будет использован оператор NOT IN.
• boolean - проверка на равенство.

Если в фильтре указано несколько полей, то в запросе они будут объединены через оператор AND.

Сортировка

Для управления сортировкой записей необходимо воспользоваться следующими параметрами:

• sort - в этом поле необходимо указать имя поля, по которому будет происходить сортировка
• dir - этот параметр служит для указания направления сортировки в запросе. (Может принимать значения: asc и desc)

Если необходимо произвести сортировку по нескольким полям одновременно, в этих параметрах необходимо передавать массивы. Например, набор таких параметров:

sort[]=title&sort[]=id&dir[]=asc&dir[]=desc

будет соответствовать следующему выражению в sql-запросе:

ORDER BY title, id DESC

Вызов методов с параметрами

Бывает, необходимо вызвать метод маппера с параметрами. Для этого необходимо в запросе указать параметр filter_methods. Значением данного параметра должен быть массив следующего вида:

[{
    method : 'MethodName',
    args   : ['arg1', 'arg2', ...]
}, {
    method : 'MethodName 2',
    args   : ['arg1', 'arg2', ...]
}, {
    ...
}]

где:

• method - указывается название метода.
• args - указывается набор параметров, с которыми будет вызван этот метод.

Если необходимо вызвать только 1 метод с параметрами, то в запросе достаточно будет определить параметры method и args

Создание своего обработчика

В компоненте предусмотрена возможность добавления своего обработчика параметров для модификации маппера. Для этого необходимо будет создать свой класс, который должен реализовывать интерфейс Component.API.Filter.Interface.

Данный интерфейс определяет один метод:

public function apply_to(DB_ORM_SQLMapper $mapper, Net_HTTP_Request $request, Component_API_WS_Application $app);

При вызове данный метод должен будет модифицировать полученный маппер соответствующим образом. Например, один из стандартных обработчиков:

class Component_API_Filter_Columns extends Component_API_Filter_Abstract implements Core_ModuleInterface
{
	public function apply_to(DB_ORM_SQLMapper $mapper, Net_HTTP_Request $request, Component_API_WS_Application $app)
	{
		if ($request['columns']) {
			$columns = explode(',', $request['columns']);
			if (!empty($columns)) {
				$mapper = $mapper->only($columns);
			}
		}
		return $mapper;
	}

}

Далее, созданный класс необходимо указать в настройках компонента в разделе filters.

Настройки компонента

Компонент предоставляет некоторые настройки, которые можно изменить под нужды конкретного проекта. Данные настройки необходимо переопределять в файле app/config/application.php в папке компонента.

// app/config/application.php
return array(
	'max_range' => 5000,
	'default_range'	 => 20,
	'realm' => 'api',
	'realm_title' => 'API',
	'filters' => array('*' => array(
		'range' => 'Component.API.Filter.Range',
		'sort' => 'Component.API.Filter.ColumnSort',
		'filter' => 'Component.API.Filter.Ext',
		'columns' => 'Component.API.Filter.Columns',
		'method' => 'Component.API.Filter.Method',
		'method_list' => 'Component.API.Filter.MethodList',
	)),
	'converter' =>  'JSON.Converter',
	'default_format' => 'json',
	'data_wrappers' => array(
		'json' => 'Component.API.DataWrapper.JSON',
		'csv' => 'Component.API.DataWrapper.CSV',
	),
);

где

• max_range - задается максимальное кол-во записей в результате.
• default_range - задается лимит записей по умолчанию.
• realm - указывается код защищенной области, для проверки доступа.
• realm_title - API
• filters - в этом параметре указываются обработчики GET-параметров для модификации результата.
• converter - название модуля, занимающегося конвертацией данных.
• default_format - формат данных по умолчанию.
• data_wrappers - массив всех доступных форматов представления данных.