API

Авторизация

Для авторизации используется механизм Basic HTTP.

В качестве имени пользователя выступает адрес электронной почты, в качестве пароля — API-ключ, который задаётся в профиле пользоваеля в Панели администратора магазина.

Тестирование c помощью REST-клиентов (cURL)

cURL позволяет выполнять любые HTTP методы для нужного ресурса. Можно передавать любые параметры запросов и заголовков, а также проверять ответные заголовки и данные. Инструмент коммандной строки «curl», стандартен для большинства *nix систем. Для пользователей Windows подойдёт MinGW/MSYS.

curl -X PUT www.example.com/api/entity/1 -d "some=var" -d "other=var2" -H "Accept: text/json" -I

curl --basic -X GET 'http://admin%40example.com:va1t900b3P2UCQWDHZk1MKB83963z16i@example.com/api/users/'

curl --user admin@example.com:va1t900b3P2UCQWDHZk1MKB83963z16i  -X GET 'http://example.com/api/users/'

curl --header 'Authorization: Basic YWRtaW5AZXhhbXBsZS5jb206dmExdDkwMGIzUDJVQ1FXREhaazFNS0I4Mzk2M3oxNmk=' -X GET 'http://example.com/api/users/'

$token = base64_encode("yourApiUserName:yourAPIToken");
$authHeaderString = 'Authorization: Basic ' . $token;

curl --header "Accept: application/json"

curl --header "Content-type: application/json"

Диаграмма классов

Процесс обработки запроса на примере GET

Точка входа

Файл api.php — точка входа в REST API.

URL для обращения к API:

http://example.com/api.php?_d=products http://example.com/api.php?_d=products/1

При включенном mod_rewrite:

http://example.com/api/products http://example.com/api/products/1

Правило преобразования срабатывает только тогда, когда в пути сразу есть /api.

Форматы ввода/вывода

Форматы отвечают за преобразование данных из строки запроса в массив и наоборот из массива в строку ответа.

Определяется это заголовками HTTP запроса.

• ContentType — формат, в котором пришли данные;
• Accept — формат, в котором даныне нужно вернуть.

За преобразования отвечает класс Api\FormatManager. Он является синглтоном, при инициализации ему нужно передать классы обработчиков, которые доступны. Каждый обработчик формата должен реализовать интерфейс Api\IFormat. Два метода в нём отвечают за преобразование данных, а getMimeTypes в виде массива возвращает список MIME типов которые может обработать этот класс.

Доступные форматы:

• Api\Formats\Json — JSON;
• Api\Formats\Text — Plain Text.

Объекты REST

Ключевая единица модели REST — это объекты, в нашем случае будем называть их сущности. Для работы с ними используется классы унаследованные от абстрактного Api\AEntity.

Каждая сущность должна обязательно реализовывать 4 базовых метода соотвествеющих HTTP.

• Для получения списка обектов, либо одного, если указан $id, параметры для фильтрации придут в $params:

  abstract public function index($id = '', $params = array());
  

• Для создания объекта. Свойства объекта придут в $params. В случае пусого массива свойств, либо наличия идентификатора объекта в адресе, запрос автоматически будет сформирован со статусом STATUS_METHOD_NOT_ALLOWED и отправлен до выова этого метода.В случае успеха метод должен возвращать статус STATUS_CREATED:

  abstract public function create($params);
  

• Для обновления объекта. Cвойства объекта придут в $params. Идентифиактор в $id. В случае пусого массива свойств, либо пустого идентификатора объекта в адресе, запрос автоматически будет сформирован со статусом STATUS_METHOD_NOT_ALLOWED и отправлен до вызова этого метода:

  abstract public function update($id, $params);
  

• Для удаления объекта. Идентифиактор придёт в $id. В случае пустого идентификатора объекта в адресе, запрос автоматически будет сформирован со статусом STATUS_METHOD_NOT_ALLOWED и отправлен до вызова этого метода.В случае успеха метод должен возвращать статус STATUS_NO_CONTENT:

  abstract public function delete($id);
  

Привилегии

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

Привязка к привилегиям осуществляется посредством указания в классе сущности соответствия названий привилегий методам класса. На примере Api\Entities\Users:

public function privileges()
{
    return array(
        'create' => 'manage_users',
        'update' => 'manage_users',
        'delete' => 'manage_users',
        'index'  => 'view_users'
    );
}

Создание, обновлнение и удаление — это manage_users, просмотр — view_users.

Вложенные сущности

Связи “многие ко многим” быть не может. Это ограниение введено специально для исключения путаницы. Считается, что в магазине большая часть объектов устроена так, что один объект будет более зависим от другого. Например, в случае с категориями и товарами это категории, потому что они являются “контейнером” для товаров.

Связь реализуется таким образом. В родителя добавляется функция возвращающая названия её дочернних сущностей:

public function childEntities()
{
    return array(
        'products'
    );
}

После этого все запросы вида /родитель/:id_родителя/потомок, обрабатываются так (на примере categories/3/products):

• выделяются оба объекта из пути, id родителя обязателен;
• создаётся объект родителя;
• вызывается метод родителя index с параметром id для получения данных о родительской сущности;
• если статус, возвращённый методом index родителя 200 (STATUS_OK), то данные передаются в потомка и вызывается соответствующий HTTP метод потомка. В нём уже доступны данные о родителе, в качестве возвращаемого значения будет результат его работы;
• если статус, возвращённый методом index родителя не 200, то будет возращён результат его работы.