Отличный backend для любых мобильных приложений 2021

Эта статья предназначена для разработчиков, которые находятся в поиске оптимального бэкенда для своего мобильного приложения.

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

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

Проблемы и решения

Документация для API

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

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

Вот как выглядит код backend разработчика:

<?php namespace Menu\Model\ExternalApi\Menu; use \ExternalApi\Model\AbstractMethods\AbstractGet; /** * Метод API "menu.get". Возвращает объект пункта меню по ID. */ class Get extends AbstractGet { //..... /** * Возвращает категорию по ID * * @param string $token Авторизационный токен * @param integer $menu_id ID пункта меню * * @example GET api/methods/menu.get?token=2bcbf947f5fdcd0f77dc1e73e73034f5735de486&menu_id=1 * Ответ * <pre> * { * "response": { * "menu": { * "id": "2", * "title": "Оплата", * "hide_from_url": "0", * "alias": "payment", * "parent": "0", * "public": "0", * "typelink": "article", * "html": "<p>Текст статьи или шаблона</p>", * "link": "http://site.ru/link/", * "mobile_public": "0", * "mobile_image": null, * "affiliate_id": "0" * } * } * } * </pre> * @return array * @throws \ExternalApi\Model\Exception */ function process($token = null, $menu_id) { //... Тут тело метода API, формирование массива $response return $response; } }

Вот так выглядит построенная документация со стороны фронтенд программиста:

Документация строится в разрезе версий и языков для каждого метода. Как только программист размечает свою документацию на нескольких языках, соответствующие переключатели (язык и версии) появляются в документации.

Логирование

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

В ReadyScript в административной панели в настройках модуля Внешнее API есть пункт  Журнал запросов к API, который открывает подробный список всех произведенных к API запросов с удобной фильтрацией.

Лог показывает Дату, время, IP, метод, статус ответа, параметры входящего запроса, тело ответа на запрос.

Фронтенд разработчик приложения должен иметь доступ в данный раздел. Понятные и достаточно подробные сообщения об ошибках окончательно исключают необходимость взаимодействия фронт и бек разработчиков.

Версионирование и языки

Модуль "Внешнее API" поддерживает возможность версионности методов API. Это означает, что метод различных версии может иметь различный набор параметров, а также возвращать различный результат.

Пример вызова метода news.getList версии 1 /api/methods/news.getList?token=abcd...&v=1

Пример вызова метода news.getList версии 2 /api/methods/news.getList?token=abcd...&some_param=345&v=2

Пример метода API news.getList, который имеет 3 версии:

namespace ModuleName\Model\ExternalApi\News; class getList extends \ExternalApi\Model\AbstractMethods\AbstractGetList { ... // Возвращает 5 последних новостей // Будет вызван при обращении к /api/methods/news.getList?v=1&.... // Справка версии 1 будет построена по комментарию к данной функции protected function process($token) { //Здесь реализация API версии 1 } // Возвращает 5 последний новостей + информация об авторе каждого поста // Будет вызван при обращении к /api/methods/news.getList?v=2&.... // Справка версии 2 будет построена по комментарию к данной функции protected function processVer2($token, $param1) { //Здесь реализация API версии 2 } // Возвращает 5 последний новостей + информация об авторе каждого поста + все комментарии к посту // Будет вызван при обращении к /api/methods/news.getList?v=3&.... // Справка версии 3 будет построена по комментарию к данной функции protected function processVer3($token, $param1) { //Здесь реализация API версии 3 } }

Язык, на котором следует вернуть результат передается через необязательный параметр lang (по умлчанию он равен ru). В случае, если параметр lang передан, перед выполнением метода API, модуль устанвливает указанный язык в качестве текущего в системе на время выполнения данного запроса.

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

Пример:

namespace ModuleName\Model\ExternalApi\News; class getList extends \ExternalApi\Model\AbstractMethods\AbstractGetList { ... /** * Описание метода для справки на русском языке * #lang-en: Method description in English * #lang-de: Beschreibung des Verfahrens in Deutsch * * @param string $token Авторизационный токен * #lang-en: Authorization token * #lang-de: Autorisierungs-Token * * @param string $param1 Произвольный параметр * #lang-en: Custom option * #lang-de: Benutzerdefinierte Option * * @example * GET /api/methods/news.getList?token=abcd¶m1=1234 * <pre> * { * "response": { * "news": [ * { * "id": 1, * "title": "Заголовок новости 1" * }, * { * "id": 2, * "title": "Заголовок новости 2" * }, * ] * } * } * </pre> * * @return array массив со списком новостей. Описание ключей * response.news.id - ID новости * response.news.title - Название новости * * #lang-en: Array of news. Keys descriptions: * response.news.id - ID of news * response.news.title - Title of news * * #lang-de: Array von Nachrichten. Tastenbeschreibungen: * response.news.id - ID der Nachrichten * response.news.title - Titel der Nachrichten */ protected function process($token, $param1) { //... } }

Авторизация и готовые методы

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

В ReadyScript для этого есть готовый метод API. Достаточно выполнить POST запрос на /api/methods/oauth.token?grant_type=password&client_id=myapp&client_secret=myappsecret&username=demo_example.com&password=xxxxxxx

И получить в ответ JSON со сведениями об авторизационном токене и полными сведениями о пользователе.

{ 'response': { 'auth': { 'token' => '38b83885448a8ad9e2fb4f...', 'expire' => '1504785044', }, 'user': { "id": "1", "name": "Иван", "surname": " Петров", "midname": "Иванович", "e_mail": "admin3@example.com", "login": "admin3@example.com", "phone": "+7(xxx)xxx-xx-xx", "sex": "", "subscribe_on": "0", "dateofreg": "2016-03-14 19:58:58", "ban_expire": null, "last_visit": "2016-11-09 15:29:14", "is_company": "0", "company": "", "company_inn": "", "data": [], "push_lock": null, "user_cost": null, "birthday": null, "fio": "Моя фамилия Супервизор тест тест", "groups": [ "guest", "clients", "supervisor" ] }, 'site_uid' : "38b83885448a8ad9e2fb4f..." } }

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

С одной стороны, готовые методы – это отличный пример того, как могут быть реализованы методы API, с другой – это готовые методы, которыми реально можно пользоваться.

Для того, чтобы увидеть полный список всех методов API, которые есть в платформе достаточно включить в административной панели в разделе Веб-сайт -> Настройка модулей -> Внешнее API опцию «Включить возможность видеть справку по внешнему API» и перейти по ссылке /api/help/  

Разграничение прав пользователей

Доступ к авторизованным методам API можно получить только имея токен авторизации, а данный токен можно получить только для некоторого объекта приложения(не зря в методе авторизации присутствует client_id, client_secret).

Объект приложения – с технической точки зрения – это класс, который имеет свой client_id и client_secret, в котором необходимо задекларировать все методы API, с которыми будет работать данное приложение.

Также непосредственно внутри реализации каждого метода API всегда можно бросить исключение, что будет обработано и возвращено в JSON API как ошибка.

Регистрация Push-токенов, отправка Push уведомлений

Push-уведомления – это базовая фишка любого приложения, но не многие понимают как это устроено «под капотом» и что для этого необходимо на стороне backend’а.

В доставке сообщений участвуют следующие сервисы: Ваш backend, сервис Firebase Cloud Messaging, мобильное устройство вашего клиента.

Firebase Cloud Messaging (FCM) – выступает в роли сервера, который держит связь со всеми клиентами вашего приложения. Именно он выдает push-token или идентификатор устройства, используя который потом можно конкретному человеку отправить push уведомление.

Именно в настройках FCM, вам нужно будет загрузить необходимые файлы и сертификаты от Apple и Google для вашего конкретного приложения. Только после этого будет возможна связь приложения и FCM.

Рассмотрим теперь детально последовательность действий приложения по получению и push-token и сообщения его backend’у.

1. Клиент запускает мобильное приложение.
2. Приложение связывается с FCM и получает push-token.
3. Приложение отправляет вашему бэкенду связку auth-token(если есть) + push-token.
4. Бэкенд сохранят у себя в базе полученные сведения.

Далее, когда бэкенд желает отправить push-уведомление клиенту, действия выполняются в следующем порядке:

1. Бэкенд находит auth-token по ID пользователя и client_id (ID приложения), которому нужно отправить сообщение
2. Бэкенд находит push-token, который связан с auth-token
3. Бэкенд отправляет запрос в FCM, где есть push-token и тело сообщения
4. FCM связывается с конкретным мобильным приложением и доставляет ему сообщение

Как видно, из написанного выше, бэкенд должен иметь методы API для сохранения push-token’а, а также уметь работать с FCM для отправки push уведомлений. ReadyScript умеет это делать из коробки.

Для регистрации push-token’а достаточно выполнить GET или POST запрос к API:

/api/methods/push.registerToken?token=f49d5fcd051aa917e8d3b37e112a6226d0bec863&push_token=2a6226d0bec863...

Также допускается передавать push-token бэкенду в момент авторизации пользователя в приложении, для этого достаточно добавить параметр custom[push-token] в запросе к методу oauth.token

Готовая админка для бэкенда

Данные, которые отображаются в мобильном приложении должны где-то администрироваться. То есть должен быть интерфейс, куда заходят контентщики, модераторы или администраторы приложения и работают с контентом приложения.

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

Программисту в ReadyScript не нужно писать свой HTML с формами. Достаточно описать состав полей ORM объектов средствами ООП и все формы система будет строить автоматически. Более того, структура базы данных будет приведена в соответствие с описанием ORM объектов.

ReadyScript предоставляет удобные инструменты для создания виждетов, из которых можно собирать удобны dash-board (сводку информации).

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

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

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

Какие приложения пользуются внешним API ReadyScript?

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

Наши внешние API мы также используем в наших Desktop приложениях, разработанных на стеке Electron.js + Angular.

Приложения хорошо себя показали на реальных нагрузках, об одном из наших клиентов, мы написали обзорную статью. JSON API работают быстро и стабильно.

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

Для каких приложений можно выбрать ReadyScript в качестве бэкенда?

Хотя фреймворк ReadyScript особенно заточен для электронной коммерции и имеет для этого огромное число базовых сущностей(товары, доставки, оплаты, заказы, склад, цены, …), которые хорошо спроектированы и документированы, сфера его применения этим не ограничивается.

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

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

Лицензирование

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

ReadyScript обладает самой гибкой системой лицензирования. Вы можете бесконечно разрабатывать и тестировать ваш сервис на локальных доменах *.local, *.test.

30 дней можно использовать trial-версию ReadyScript на «боевом» домене, далее потребуется приобрести временную или бессрочную лицензию на продукт.

Технологический стек. Полезные ссылки

Для работы CMS ReadyScript требуется PHP 7.1+, MySQL 5+

Страница загрузки дистрибутива CMS ReadyScript – https://readyscript.ru/download/

Документация по разработке модулей для ReadyScript – https://readyscript.ru/dev-manual/dev_get_started.html

Документация по разработке методов внешнего API – https://readyscript.ru/dev-manual/dev_external_api.html

Общая документация для разработчиков ReadyScript - https://readyscript.ru/dev-manual/