Разработка собственных методов внешнего API. Пошаговая инструкция

В недавней статье мы описывали общие возможности нашего движка внешних API.

В этой статье мы расскажем, как с нуля создать метод внешнего JSON API на платформе ReadyScript. В качестве потребителя данного API может выступать любое приложение, будь то мобильное или Desktop приложение или любой внешний сервис.

В рамках данной статьи мы рассмотрим какие базовые абстрактные методы API нам предлагает ReadyScript и создадим на базе двух из них свои собственные методы.

Задача

Задание, которое мы сегодня будем выполнять звучит так: «Разработать 2 метода внешних API для получения списка брендов, а также получения одного бренда по ID. Получение бренда по ID должно быть доступно только для авторизованных пользователей».

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

Установка ReadyScript

Итак, для начала нам будет необходимо установить локально платформу ReadyScript, например на домен backend.local (Мы будем ссылаться на данный домен далее по тексту). Если вы ведете разработку на Windows, то сперва необходимо установить LAMP-окружение. Наиболее удобным для этого является программа OpenServer. Обратите внимание, что для ReadyScript требуется PHP 7.1+ и Mysql с выключенным Strict Mode, это означает, что в my.cnf файле должно быть установлено пустое значение для параметра sql_mode (sql_mode = “”).

Для установки ReadyScript достаточно скачать файл rs.php и запустить его из браузера на вашем локальном домене (backend.local/rs.php), далее следуйте инструкциям, отображаемым установщиком. Вы можете установить любую редакцию ReadyScript, функция внешних API есть во всех редакциях.

Начало разработки. План действий

1. Всю разработку мы будем вести в отдельном модуле, соответственно первым делом мы создадим простейший модуль MyApi по инструкции.
2. Далее мы создадим и зарегистрируем класс приложения, которое будет работать с нашим API, так как нам нужны будут функции требующие авторизации.
3. Далее мы приступим к разработке непосредственно методов API.

Подготовка к разработке

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

1. В разделе Управление -> Настройка системы установим опции:
   • Подробно отображать информацию об исключениях = Да
   • Всегда проверять шаблоны на предмет модификации = Да
   • Включить кэширование данных = Нет
2. В разделе Веб-сайт -> Настройка модулей -> Внешнее API установим:
   • Разрешить работу API только на следующем домене = пустое поле
   • API ключ = пустое поле
   • Включить возможность видеть справку по внешнему API по ссылке /api/help = Да
   • Отображать детальную информацию по внутренним ошибкам при вызове API = Да
   • Включить логирование запросов = Да
3. В разделе Товары -> Бренды заведем несколько брендов, с которыми далее мы будем работать.

Данные настройки нужно устанавливать только на время разработки, в продакшене нужно задать противоположные значения, API-ключ на продакшене не должен быть пустым.

Создаем модуль MyApi

В папке /modules нашего сайта создаем следующую структуру папок:

• myapi //Корневая папка модуля
  • config //Папка для конфигурационных классов
  • model //Папка для моделей данных
    • apptypes //Папка для классов внешних приложений 
    • externalapi //Папка для методов внешних API

Чтобы модуль корректно был идентифицирован системой, в папке myapi/config необходимо создать файл file.inc.php, содержащий базовые сведения о модуле и его настройки.

Так как у нас не будет никаких настроек модуля, файл должен содержать пустую декларацию класса, потомка \RS\Orm\ConfigObject.

<?php namespace MyApi\Config; use RS\Orm\ConfigObject; /** * Класс, описывающий настройки модуля */ class File extends ConfigObject { //У нас нет настроек, поэтому класс пустой. Но его наличие обязательно! }

Создадим рядом с файлом file.inc.php манифест (файл описания параметров) модуля module.xml:

<?xml version="1.0" encoding="utf-8"?> <config> <defaultValues> <name multilanguage="true">Тестовый модуль для внешних API</name> <description multilanguage="true">Добавляет 2 метода API MyBrand.GetList и MyBrand.Get</description> <version>1.0.0</version> <author>ReadyScript lab.</author> </defaultValues> </config>

Теперь у нас есть минимальный модуль, который определяется системой и мы можем перейти в административную панель в раздел Веб-сайт -> Настройка модулей -> Мой API и нажать установить модуль.

Создаем и регистрируем класс внешнего приложения

С методами API, требующими авторизации, могут работать только заранее определенные и зарегистрированные в системе приложения. Приложение должно быть оформлено специальным классом, наследником RS\RemoteApp\AbstractAppType.

Опишем класс с именем MyCustomApp в файле modules/myapi/model/apptypes/mycustomapp.inc.php

<?php namespace MyApi\Model\AppTypes; use ExternalApi\Model\App\AbstractAppType as AbstractAppType; use MyApi\Model\ExternalApi\MyBrand\Get as MyBrandGet; /** * Наше тестовое приложение */ class MyCustomApp extends AbstractAppType { /** * Возвращает строковый идентификатор приложения * * @return string */ public function getId() { return 'my-custom-app'; //Любой ID, который будет характеризовать ваше приложение } /** * Проверяет SHA1 от секретного ключа client_secret, который должен * передаваться вместе с client_id в момент авторизации * * @param string $client_secret - секретное слово на клиентской стороне * @return string */ public function checkSecret($client_secret) { //Ожидаем в client_secret пароль: password123, sha1('password123') = cbfdac6008f9cab4083784cbd1874f76618d2a97 //Не храним в коде приложения пароль в открытом виде. return sha1( $client_secret ) == 'cbfdac6008f9cab4083784cbd1874f76618d2a97'; } /** * Метод возвращает название приложения * * @return string */ public function getTitle() { return t('Наше тестовое мобильное приложение'); } /** * Метод возвращает массив, содержащий требуемые права доступа к методам API для приложения * * @return array * [ * 'метод1' => код действия, * 'метод2' => [код действия, код действия, ...] * ... * ] */ public function getAppRights() { return [ 'mybrand.getList' => self::FULL_RIGHTS, //Полные права. Права будет проверяться внутри метода в вашей функции. 'mybrand.get' => MyBrandGet::RIGHT_READ, ]; } /** * Авторизация будет проходить только, если пользователь будет * принадлежать группам, которых вернет данный метод. * * @return array * ["group_id_1", "group_id_2", ...] */ public function getAllowUserGroup() { return ['admins']; //Пользователь должен будет принадлежать группе Администраторы } }

Как видно из кода выше, класс содержит сведения о названии приложения(его нужно придумать), идентификаторе(нужно придумать), методах API, с которыми будет работать приложение, а также о правах с которыми будут вызываться данные методы. В качестве права может выступать любая константа, так как проверять эти права будете далее вы в своем же коде метода API. Также в классе описаны группы, в которых должен состоять пользователь, чтобы пройти авторизацию.

В случае, если бы наше приложение отправляло push-уведомления, необходимо было бы имплементировать интерфейс \PushSender\Model\App\InterfaceHasPush и описать все пуши, которые данное приложение отправляет, но в нашем случае это не требуется.

Теперь нам необходимо зарегистрировать в системе наше приложение. Для этого создаем обработчик события getapps в файле /config/handlers.inc.php

<?php namespace MyApi\Config; use MyApi\Model\AppTypes\MyCustomApp; use RS\Event\HandlerAbstract; /** * Класс, в котором мы описываем обработчики событий */ class Handlers extends HandlerAbstract { function init() { $this->bind('getapps'); //Подписываемся на событие getapps } /** * Обработчик события getapps * * @param array $list список уже зарегистрированных в приложений от других модулей * @return array список уже зарегистрированных в приложений от других модулей вместе с нашим приложением */ public static function getApps($list) { $list[] = new MyCustomApp(); return $list; } }

Приступаем к разработке методов API

В ReadyScript существует множество готовых базовых классов для различных операций. Это означает, что достаточно создать класс потомок от одного из готовых классов и дописать только небольшую часть методов, описывающих вашу логику.

Подробно базовые классы методов API описаны у нас в документации. Использование готовых базовых классов в реальных проектах мы конечно же рекомендуем, но чтобы понимать как ими пользоваться нужно знать детально как все работает, поэтому в рамках данной статьи мы будем с нуля писать методы API, наследуясь от низкоуровневых абстракций ExternalApi\Model\AbstractMethods\AbstractMethod и ExternalApi\Model\AbstractMethods\AbstractAuthorizedMethod.

Метод mybrand.getList

Наш первый метод внешнего API будет доступен всем пользователям, даже без авторизации, поэтому выбираем в качестве базового класса ExternalApi\Model\AbstractMethods\AbstractMethod. Это самый низкоуровневый родитель, все методы API должны быть его наследниками.

На вход в наш метод, мы будем принимать два параметра: номер страницы и количество элементов на страницу. Итак, приступим к описанию кода, из которого многое будет ясно.

<?php namespace MyApi\Model\ExternalApi\MyBrand; use Catalog\Model\BrandApi; use ExternalApi\Model\AbstractMethods\AbstractMethod; use ExternalApi\Model\Utils as ExternalApiUtils; use RS\Module\AbstractModel\EntityList; /** * Класс описывает метод внешнего API MyBrand.getList */ class GetList extends AbstractMethod { protected $dao; /** * Возвращает список брендов, присутствующих в системе. Информация по каждому бренду ограничивается: ID, Названием, ссылкой на картинку * * @param integer $page Номер страницы * @param integer $pageSize Количество элементов на странице * @return array * @example GET /api/methods/mybrand.getlist * <pre> * { * "response": { * "summary": { * "page": 1, * "pageSize": 2, * "total": "14" * }, * "list": [ * { * "id": "16", * "title": "Asus", * "image": { * "original_url": "http://full.readyscript.local/storage/system/original/81676002a34107daded7349815fcd163.jpg", * "big_url": "http://full.readyscript.local/storage/system/resized/xy_1000x1000/81676002a34107daded7349815fcd163_4428c733.jpg", * "middle_url": "http://full.readyscript.local/storage/system/resized/xy_600x600/81676002a34107daded7349815fcd163_cffa770d.jpg", * "small_url": "http://full.readyscript.local/storage/system/resized/xy_300x300/81676002a34107daded7349815fcd163_a62391cf.jpg", * "micro_url": "http://full.readyscript.local/storage/system/resized/xy_100x100/81676002a34107daded7349815fcd163_4733fb31.jpg", * "nano_url": "http://full.readyscript.local/storage/system/resized/xy_50x50/81676002a34107daded7349815fcd163_25ef3206.jpg" * } * }, * { * "id": "14", * "title": "НP", * "image": null * } * ] * } *} * </pre> * */ protected function process($page = 1, $pageSize = 20) { //Специально дробим выборку на мелкие функции getDaoObject, setFilter, setOrder...., //так текущий класс будет возможно использовать в качестве базового для какой-нибудь другой //выборки в других классах. Нужно будет только переопределить некоторые методы. $this->dao = $this->getDaoObject(); $this->setFilter($this->dao, [ 'public' => 1 ]); $this->setOrder($this->dao, 'id desc'); return [ 'response' => [ 'summary' => [ 'page' => $page, 'pageSize' => $pageSize, 'total' => $this->getResultCount($this->dao), ], 'list' => $this->getResultList($this->dao, $page, $pageSize), ] ]; } /** * Возвращает DAO (Data Access Object) объект, с помощью которого можн овыбирать ORM объекты. * ORM объекты - это объекты, которые описывают сущность, представленную в БД (например, Бренд, Товар, и т.д.) * * @return BrandApi Возвращает наследника EntityList */ protected function getDaoObject() { return new BrandApi(); } /** * Устанавливает фильтр на выборку объектов * * @param EntityList $dao DAO объект * @param array $filter массив с фильтрами */ protected function setFilter($dao, $filter) { $dao->setFilter($filter); } /** * Устанавливает сортировку для выборки ORM объектов * * @param EntityList $dao DAO объект * @param string $sort Поле сортировки и направление, например "id DESC" */ protected function setOrder($dao, $sort) { $dao->setOrder($sort); } /** * Возвращает общее количество элементов, доступное для выборки * * @param EntityList $dao DAO объект * @return integer */ protected function getResultCount($dao) { return $dao->getListCount(); } /** * Возвращает список объектов * * @param EntityList $dao DAO объект * @param integer $page Номер страницы * @param integer $pageSize Количество элементов на страницу * @return array */ public function getResultList($dao, $page, $pageSize) { $result = []; foreach($dao->getList($page, $pageSize) as $orm_object) { $result[] = array_intersect_key( //Отфильтруем только нужные нам поля ExternalApiUtils::extractOrm($orm_object), //Получим массив со всеми полями ORM-объекта array_flip(['id', 'title', 'image']) ); } return $result; } }

Обратите внимание, что мы могли бы всю выборку объектов описать в методе process, но вместо этого мы разбили ее на несколько небольших методов getDaoObject, setFilter, setOrder, getResultCount, getResultList. Такой подход позволяет в будущем повторно использовать код, используя данный класс в качестве базового. Например, если нужно создать аналогичное API для выборки других объектов, достаточно сделать класс-потомок от MyApi\Model\ExternalApi\MyBrand\GetList и переопределить в нем только один метод getDaoObject. Именно такого подхода, мы придерживаемся при разработке наших базовых абстрактных классов для различных типов внешнего API.

Проверяем, наш новый метод должен появиться на странице помощи по внешним API. Для этого открываем страницу backend.local/api/help/myBrand.getList и видим следующее.

Использовать метод можно по ссылке backend.local/api/methods/myBrand.getList

Метод mybrand.get

Данный метод должен возвращать нам полную информацию об одном объекте бренда по его ID. Доступ к нему есть только у авторизованных пользователей из группы Администраторы.

В качестве базового класса, мы будем использовать ExternalApi\Model\AbstractMethods\AbstractAuthorizedMethod. Данный класс обеспечивает необходимые механизмы для проверки авторизационного токена и проверку прав.

<?php namespace MyApi\Model\ExternalApi\MyBrand; use Catalog\Model\Orm\Brand; use ExternalApi\Model\AbstractMethods\AbstractAuthorizedMethod; use ExternalApi\Model\Exception as ApiException; use ExternalApi\Model\Utils as ExternalApiUtils; use RS\Orm\AbstractObject; /** * Класс описывает метод внешнего API MyBrand.get */ class Get extends AbstractAuthorizedMethod { /** * Право на чтение */ const RIGHT_READ = 'read'; /** * Возвращает комментарии к кодам прав доступа. * Текстовое обозначение права доступа будет использоваться в сообщениях об ошибках. * Метод можно будет запустить только если у приложения есть хотя бы одно из перечисленных здесь прав. * * @return [ * КОД => КОММЕНТАРИЙ, * КОД => КОММЕНТАРИЙ, * ... * ] */ public function getRightTitles() { return [ self::RIGHT_READ => t('Право на чтение данных') ]; } /** * Возвращает какой объект нужно загружать * * @return AbstractObject */ public function getOrmObject() { return new Brand(); } /** * Возвращает объект бренда с полными сведениями * * @param string $token Токен авторизации * @param integer $id ID бренда * * @return array * @example GET /api/methods/myBrand.get?token=48081b693d3c239071e5a3d2a28a4a35&id=1 * <pre> * { * "response": { * "brand": { * "id": "1", * "title": "Asus", * "alias": "asus", * "public": "1", * "image": { * "original_url": "http://full.readyscript.local/storage/system/original/39071e5a3d2a28a4a3548081b693d3c2.png", * "big_url": "http://full.readyscript.local/storage/system/resized/xy_1000x1000/39071e5a3d2a28a4a3548081b693d3c2_9e4a09f4.png", * "middle_url": "http://full.readyscript.local/storage/system/resized/xy_600x600/39071e5a3d2a28a4a3548081b693d3c2_d47e16ce.png", * "small_url": "http://full.readyscript.local/storage/system/resized/xy_300x300/39071e5a3d2a28a4a3548081b693d3c2_bda7f00c.png", * "micro_url": "http://full.readyscript.local/storage/system/resized/xy_100x100/39071e5a3d2a28a4a3548081b693d3c2_5cb79af2.png", * "nano_url": "http://full.readyscript.local/storage/system/resized/xy_50x50/39071e5a3d2a28a4a3548081b693d3c2_8467bf54.png" * }, * "description": "Расположенная на Тайване компания, производящая персональные компьютеры...", * "xml_id": null, * "meta_title": "", * "meta_keywords": "", * "meta_description": "", * "meta_custom": "", * "meta_image": "", * "meta_html_description": null * } * } * } * </pre> * @throws ApiException */ protected function process($token, $id) { //Параметр $token - обязательно перечислить в аргументах. Он будет обработан в AbstractAuthorizedMethod $this->object = $this->getOrmObject(); //Получаем объект if ($this->object->load($id)) { //Загружаем объект return [ 'response' => [ 'brand' => ExternalApiUtils::extractOrm($this->object) //Конвертируем ORM объект в массив значений ] ]; } throw new ApiException(t('Объект с таким ID не найден'), ApiException::ERROR_OBJECT_NOT_FOUND); } }

При обращении к backend.local/api/help/myBrand.get мы теперь можем увидеть документацию по нашему методу API.

Это возможно благодаря тому, что ReadyScript самостоятельно обходит все файлы, чья маска совпадает с паттерном /modules/*/model/externalapi/*/*.inc.php, находит в таких файлах классы, связанные с внешними методами API и подключает их.

Остается теперь вопрос, как проверять такой метод, ведь он требует Авторизационный токен, который можно получить выполнив POST запрос на backend.local/api/methods/oauth.token с соответствующими данному методу параметрами.

Авторизационный токен также можно получить и с помощью двух кликов через административную панель. Для этого необходимо перейти в раздел Веб-сайт -> Настройка модулей -> Внешнее API -> Авторизационные токены (справа) -> Кнопка Добавить (вверху).

Выберите в открывшемся диалоговом окне ваше приложение “Наше тестовое мобильное приложение”, скопируйте Авторизационный токен в буфер обмена и нажмите на кнопку Сохранить и закрыть.

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

Использовать метод можно по ссылке backend.local/api/methods/myBrand.get?token=ВАШ_ТОКЕН&id=1

Заключение

В отличие от REST подхода, JSON API в таком виде имеет бóльшую гибкость, так как он динамически расширяем и не имеет жесткой привязки к отношениям между объектами, которая обычно в REST жестко закладывается в URL методов.

Мы показали, что добавлять методы можно достаточно быстро и не сложно. По сути, когда вся инфраструктура есть, остается только создавать классы и описывать только непосредственно логику действия вашего метода API.

Безусловно в данной статье охвачена лишь небольшая часть возможностей нашего движка внешних API, но наша цель познакомить и увлечь, обо всех остальных особенностях создания внешних методов API, вы можете прочитать в нашей документации для разработчиков.

Представленный в данной статье код модуля, можно скачать здесь.