Веб-интерфейс обеспечивает функциональность обмена данными с сервером в соответствии с парадигмой REST API.
Среда разработки предоставляет базовые классы Collection
и Model
спроектированных по подобию таких-же классов в Backbone.js.
Шаблон строки запроса к API: {{base_url}}/{{collection}}[/{{model_id}|{collection_method}}[/{model_method}][/{method_argument}]]
debug
: при указании параметра в вывод результатов запросов будут добавлены тестовые данные фреймворка.
bulk
: параметр указывает API в каком объеме должны быть возвращены данные результата запроса.
Возможные значения:
-
ids
- результатом запроса будет массив идентификаторов; -
compact
- выполняется выборка данных только из источника коллекции сущностей (значение по умолчанию для коллекций); -
full
- данные модели дополняются данными связанных сущностей.
fallback
: фреймворк переключается в режим возврата статических данных из JSON-файлов, путь к дирректории файлов определяется константой STATIC_DIR
. Название файла составляется из элементов конечной точки разделённых символом нижнего подчёркивания _
. В случае если файл не был найден, возвращается 404-я ошибка с описанием проблемы. Необходимо передавать true
в значении параметра
fields
: перечень запрашиваемых атрибутов, переданных через запятую. Перестает влиять на результат запроса при указании параметра bulk
. По умолчанию результат запроса содержит все поля источника данных, которые не упоминаются в excluded_fields
.
excluded_fields
: перечень атрибутов модели, которые не должны присутствовать в результате запроса.
where
: условие выборки из источника данных. Логические выражения перечисляются через запятую (оператор AND
).
В качестве первого аргумента логического выражения указывается название параметра запрашиваемой сущности. Вторым аргументом передаётся его значение.
Аргументы логического выражения разделяются знаком :
(равно), ::
(строгое соответствие) или !:
(не равно).
Фреймворк проверяет наличие полей в источнике данных сущности и для несуществующих параметров API вернёт 500-ю ошибку. Использование простого равенства для строкового поля источника данных подразумевает его замену на опреатор
LIKE
в выражении условия поиска, а значение параметра будет обрамлено символом%
для поиска по вхождению строки в значение поля результатов выборки. Для поиска по точному совпадению со значением используйте знак::
.
count
: количество элементов в ответе. По умолчанию определяется константой FETCH_DEFAULT_COUNT
в настройках фреймворка
offset
: смещение результатов запроса. По умолчанию определяется константой FETCH_DEFAULT_OFFSET
в настройках фреймворка
order
: название параметра, по которому выполняется сортировка результатов запроса. Для сортировки по возрастанию перед названием атрибута добавляется знак -
. Для уточнения сортировки можно передать несколько атрибутов через запятую. Если не определено, то результат сортируется по полю created_time
, по убыванию
В результате запроса вы всегда получите JSON-объект.
Запрашиваемые даннные передаются в атрибуте data
.
В атрибуте meta
передаются метаданные ответа API. Например в случае ошибочного запроса, описание ошибки будет передано в метаданных.
Ответ может дополнятся такими данными как например описанием постраничной навигации или параметров модели данных.
Пример ответа на запрос коллекции данных:
{
"meta": {
"code": 200,
"length": 5,
"paging": {
"current": 1,
"prev": 0,
"next": 2,
"last": 3
},
"total": 15
},
"data": [
{...},
{...},
{...},
{...},
{...}
]
}
Пример ответа об ошибке:
{
"meta": {
"code": "500.42000",
"error_type": "PDOException",
"error_message": "SQLSTATE[42000]: Syntax error or access violation: ..."
},
"data": null
}
class Items extends Collection {
static $classModel = 'Item';
/** API Method
*
* param $arguments
* аргументы метода переданные в URL запроса после названия метода
*
* param $data
* хеш параметров из программной среды, обычно это массив $_GET, $_POST или $_PUT
*/
function get_methodName (array $arguments, array $data = []) {
...
return $result;
}
function post_methodName (array $arguments, array $data = []) {
...
return $result;
}
function put_methodName (array $arguments, array $data = []) {
...
return $result;
}
function delete_methodName (array $arguments) {
...
return $result;
}
}
Пользовательские методы HTTP-запросов объявляются в классе, с приставкой 'get_', 'post_', 'put_' или 'delete_' в зависимости от метода HTTP-запроса.
class Item extends Model {
protected $_table = "`db_name`.`table_name`";
function get_lastmodify() {
$ts = $this->_table->select('updated_time')
->order("`updated_time` desc")
->limit(1)
->fetchColumn();
return date("c", $ts);
}
}