Home

Документация API Литера 5

Добро пожаловать!

API (Application Programming Interface / программный интерфейс приложения) Литеры 5 - это инструментарий для подключения возможностей Литеры к корпоративным системам подготовки текстов. Возможно использование API как с облачной версией Литеры так и с установками её автономной версии.

Понятия и терминология

• Литера (сервер Литеры) - облачный сервер Литеры 5 по адресу https://litera5.ru, либо корпоративная установка автономного сервера Литеры размещённого в локальной сети Партнёра.
• Партнёр - организация заключившая договор с компанией ООО "Орфограмматика" и получившая лицензию на использование API Литеры.
• Сайт (корпоративная система подготовки текста) - веб-сайт Партнёра в который встраиваются инструменты взаимодействия с Литерой.
• Пользователь - пользователь сайта партнёра, которому нужно подготовить текст с использованием инструментов Литеры.
• Ключ (секретный ключ, API_SECRET_KEY) - секретный ключ партнёра, выдаётся администрацией Литеры по запросу партнёра. Этот ключ нужно держать втайне, поскольку именно он будет использоваться для подтверждения полномочий пользователей и сайта при работе с Литерой.

Общие положения

Взаимодействие с API организовано в форме обмена с Литерой запросов по протоколу HTTP(s). Все запросы осуществляются преимущественно методом POST, в кодировке UTF-8 с телом запроса в виде объекта JSON (Content-type: application/json). Все значения параметров запроса (полей объекта JSON) интерпретируются как строки, если это не оговорено отдельно. Для авторизации используется подпись всех запросов/ответов функцией md5(time + ${message} + API_SECRET_KEY).

> Изучить подробнее

Варианты использования

Настройка

API Литеры позволяет решать следующие задачи:

• Настройки обратной связи (куда сообщать о результатах работы с текстом)
• Настройка внешнего вида Литеры
• Односторонняя репликация пользователей (можно создавать новых пользователей и редактировать существующих Литеры средствами API)
• Настройка возможностей пользователя в Литере

> Изучить подробнее

Проверка текста с использованием интерфейса Литеры 5 и последующей обработкой результатов в её редакторе

Этот вариант использования предназначен для получения проверенного и исправленного текста. Все исправления производятся в интерфейсе Литеры и фактически на сайте Литеры. Обработанный текст возвращается на сервер Сайта партнёра.

Типичный сценарий организации работы по этому варианту выглядит примерно так: на сайте партнёра, в форме редактирования текста размещается дополнительная кнопка "Проверить в Литере". При нажатии на эту кнопку сервер сайта отправляет запрос на сервер Литеры инициирующий процесс проверки текста. В ответ на этот запрос сервер Литеры возвращает URL с текстовым редактором Литеры, в котором производится проверка, отображаются результаты этой проверки и возможна работа над ошибками. Сайт партнёра открывает этот URL в браузере пользователя либо в новом окне, либо непосредственно в своего Сайта при помощи iframe. Открыв страничку по этому, полученному от сервера Литеры, URL пользователь увидит обычный интерфейс Литеры по работе с результатами проверки. Плюс в него добавляются две дополнительных кнопки "Вернуться на Сайт партнёра без сохранения результатов работы над текстом" и "Вернуться на Сайт партнёра с передачей туда результатов работы над текстом". Внешний вид (иконку и надписи на кнопках) можно задать в настройках API. После нажатия на одну из этих двух кнопок, сервер Литеры выполняет запрос к серверу Сайта с соответствующим содержимым.

> Изучить подробнее

Проверка текста без использования интерфейса Литеры 5 и последующей самостоятельной обработкой результатов

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

Для организации работы по этому варианту нам не нужен пользователь с его браузером. Всё взаимодействие происходит между некоторой программой (Сайтом партнёра или каким-то скриптом) и сервером Литеры. Сайт выполняет запрос на проверку текста, затем ждёт периодически спрашивая сервер Литеры о готовности результатов. Затем как-то самостоятельно обрабатывает полученные результаты.

> Изучить подробнее

Справочник методов API

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

Методы на стороне Литеры

Это, собственно, все функции, которые предлагает API Литеры для решения задач партнёра по интеграции со своим сайтом.

• POST setup - общие настройки партнёра действующие на всех пользователей
• POST user - создание/изменение настроек пользователя
• POST check - запуск проверки и последующей обработки текста пользователем
• GET iframe - редактор Литеры с обработкой ранее запущенной проверки текста
• POST check-ogxt - запуск проверки текста для последующей машинной обработки результатов
• POST check-ogxt-results - проверка результатов стартовавших в результате выполнения функции check-ogxt

Методы на стороне сайта партнёра

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

• POST on-save-corrected - сохранение результатов работы над текстом на Сайт партнёра
• POST on-iframe-failure - обработка ошибок в редакторе Литеры
• GET return-to-cms - возвращение пользователя из редактора Литеры на Сайт партнёра
• POST on-initial-stats - получение статистического отчёта после первичной проверки

Модели результатов проверки

• Отчёт о результатах проверки
• Статистический отчёт

Клиентские воплощения

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

• litera5-api-php-client - программная библиотека для работы с API Литеры из PHP.
• litera5-api-js-client - программная библиотека для работы с API Литеры из JavaScript/TypeScript (nodejs).

Вспомогательные ресурсы

Следующие материалы могут оказаться полезны в ходе интеграции:

• litera5-api-cli - консольное приложение для работы с API Литера в ручном режиме (nodejs).
• ogxt-utils - программная библиотека для работы с текстовым форматом OGXT и результатами проверки (JavaScript / TypeScript).
• ogxt-utils-webpack-demo - пример использования OGXT утилит в веб-приложении собираемом при помощи webpack (JavaScript).
• litera5-api-css-themes - примеры стилей для самостоятельной настройки внешнего вида результатов проверки в редакторе Литеры (scss).