BPanchenko / protosite-api

Среда разработки REST API

Protosite API

Веб-интерфейс обеспечивает функциональность обмена данными с сервером в соответствии с парадигмой REST API.

Среда разработки предоставляет базовые классы Collection и Model спроектированных по подобию таких-же классов в Backbone.js.

Шаблон строки запроса к API: {{base_url}}/{{collection}}[/{{model_id}|{collection_method}}[/{model_method}][/{method_argument}]]

Общие GET-параметры запросов к API

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
}

Конечные точки API как публичные методы объектов.

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);
    }
}