Открывайте внешнее API для партнеров на вашем сайте

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

Также мы опубликовали бесплатный модуль «API-фильтр» в нашем маркетплейсе, который позволяет исключать ненужные данные из ответов API с помощью специальных масок (JSON Path). Расскажем ниже об этом подробнее.

Кому необходима новая функциональность?

Если вы являетесь оптовым поставщиком товаров для других магазинов или специализируйтесь на предоставлении услуг дроп-шиппинга, то наверняка у вас уже возникал вопрос: “Как передавать актуальную информацию по товарам, остаткам и ценам своим партнерам?”.

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

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

Но почему это нельзя было делать раньше? Раньше был только один endpoint (адрес подключения /api-ключ/methods/… ), т.е. вам нужно было предоставить партнерам тот же API-ключ, который используется и в ваших внутренних приложениях, что не позволяло в полной мере разграничить права для партнеров и ваших внутренних приложений.

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

Как настроить независимый адрес для внешнего API?

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

Создавайте одно виртуальное приложение на одно направление интеграции. Например, для всех партнеров можно создать одно внешнее приложение «Розничные партнеры», разрешить данному приложению использовать методы, связанные с получением информации о товарах (product.getList, product.get).

Далее на новой вкладке «Подключение» установите флажок «Использовать отдельный адрес API» и придумайте уникальный API-ключ (не менее 16 символов), который и будет формировать уникальный адрес точки подключения.

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

После сохранения внешнего приложения, в списке у данного приложения будет отображен базовый адрес API (endpoint), а также адрес справки.

Как ограничить данные, возвращаемые в методах API?

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

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

В разделе «Правила фильтрации» можно создавать новые правила или работать с существующим списком правил фильтрации.

Каждое правило фильтрации состоит из следующих полей:

• Название
  Это внутреннее название, для удобства идентификации правила в списках.
• Контекст запуска метода API
  Это поле позволяет ограничить контекст применения данного правила. Можно выбрать из трех вариантов:
  Стандартный контекст – когда к методу API идет запрос с API-ключем, заданным в настройках модуля «Внешнее API»
  Виртуальное приложение – когда к методу API идет запрос с API-ключем, заданным у виртуального приложения
  Любой – означает, что контекст запуска метода API не проверяется
• Виртуальное приложение
  Данное поле появляется, если выбран контекст запуска «Виртуальное приложение». Здесь необходимо выбрать конкретное виртуальное приложение, для которого данное правило должно срабатывать.
• Методы API
  Поле предназначено для выбора одного или нескольких методов API, результат которых должно фильтровать данное правило.
• Флаг «Включено»
  Только включенные правила участвуют в фильтрации данных. Флаг позволяет временно отключить неактуальные правила.
• Правила исключения ключей из итогового JSON
  Самое важное поле, в котором необходимо описывать непосредственно JSON Path пути для исключения ненужных секций. Подробнее разберем данное поле ниже с примерами.
• Флаг «Протестировать применение правил»
  Установите данный флаг для проведения тестирования работоспособности правил фильтрации прямо на этой странице. Подробности будут рассмотрены далее.

Подробнее остановимся на поле «Правила исключения ключей из итогового JSON». Чтобы описать, какую секцию необходимо исключить из JSON, необходимо использовать правила в формате JSONPath:

Например: $.response.list[*].price

Если исходный JSON будет иметь следующий вид

{ "response": { "list": [ { "id": 1, "title": "Товар 1", "price": 100 }, { "id": 2, "title": "Товар 2", "price": 200 } ] } }

То правило, представленное в примере, модифицирует его так:

{ "response": { "list": [ { "id": 1, "title": "Товар 1", }, { "id": 2, "title": "Товар 2", } ] } }

Подробный разбор:

JSONPath – это известный язык запросов, используемый для навигации по разветвленным JSON данным. С помощью данного языка запросов можно очень гибко описывать объект, который необходимо найти и исключить.

Опишем основные синтаксические элементы JSONPath, которые могут использоваться в запросах.

Предположим, у нас есть следующий JSON, возвращаемый некоторым вымышленным методом API:

{ "store": { "book": [ { "category": "reference", "author": "Nigel Rees", "title": "Sayings of the Century", "price": 8.95 }, { "category": "fiction", "author": "Evelyn Waugh", "title": "Sword of Honour", "price": 12.99 }, { "category": "fiction", "author": "Herman Melville", "title": "Moby Dick", "isbn": "0-553-21311-3", "price": 8.99 }, { "category": "fiction", "author": "J. R. R. Tolkien", "title": "The Lord of the Rings", "isbn": "0-395-19395-8", "price": 22.99 } ], "bicycle": { "color": "red", "price": 19.95 } } }

Покажем на примере, как, используя JSONPath, исключать различные элементы из JSON-данных. Все примеры, которые представлены ниже вы можете протестировать в диалоге создания нового правила.

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

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

Для проведения тестирования правил фильтрации, установите флажок «Протестировать применение правил». Ниже отобразятся два поля: «Исходный JSON», «Итоговый JSON».

Вставьте в поле «Исходный JSON» данные, которые вы желаете отфильтровать, затем изменяйте правила фильтрации – в реальном времени в поле «Итоговый JSON» вы сможете видеть результат применения правил.

Важно: новый модуль будет работать только с самой свежей версией платформы ReadyScript.

Как преподнести информацию, что у вас есть публичные API?

После того, как вы настроили внешнее API на отдельном адресе, настроили правила фильтрации, необходимо как-то сообщить вашим партнерам о том, что у вас есть внешнее API. Для этого поручите вашему ИТ-специалисту подготовить информационную статью и разместите ее на вашем сайте с помощью раздела Веб-сайт -> Меню.

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

https://вашдомен.ру/api-[api ключ]/help

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

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

Заключение

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

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