0

Товар успешно добавлен в корзину

Оформить заказ

Разработка собственных методов внешнего 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.

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

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

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

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

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

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

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

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

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

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

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

Метод mybrand.getList

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

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

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

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

mybrand_getlist

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

Метод mybrand.get

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

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

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

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

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

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

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

add-token

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

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

Заключение

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

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

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

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


28 февраля 2021 19:45, Артем Полторанин
Рассказать друзьям: