Как устроен API Optifora
Эта страница описывает устройство API: как подтверждается личность, как развиваются версии, в каких пределах остаётся запрос, как выглядит ошибка и как ведётся обмен данными с внешним миром.
Продукт находится в разработке, и поверхность API ещё дополняется. Справочник эндпоинтов будет опубликован отдельно; на этой странице нет ни адресов, ни примеров вызовов — только механика.
Аутентификация
Каждый запрос принадлежит либо человеку, либо зарегистрированному приложению. Запрос без личности, дошедший до защищённого эндпоинта, возвращается неаутентифицированным.
- Токен BearerТокен доступа передаётся в заголовке авторизации запроса. Он подписан и сообщает только то, кому принадлежит запрос.
- Короткий срок жизниСрок жизни токена доступа измеряется минутами; длительность задаётся при развёртывании, по умолчанию — тридцать минут.
- Обновление и ротацияСессия продлевается токеном обновления, и при каждом продлении выдаётся новая пара. Если уже использованный токен обновления предъявляется повторно, все сессии этого пользователя отзываются.
- Права не зашиты в токенТокен несёт только личность; что именно человеку разрешено видеть, спрашивается у базы данных при каждом запросе. Поэтому отозванное право перестаёт работать раньше, чем истечёт уже выданный токен.
- Ключ интегратораЗарегистрированное приложение подключается по собственному ключу. Открытое значение показывается один раз — при создании; хранится его хеш и несекретный префикс, по которому ключ можно опознать.
- Доступ выдаёт организацияНасколько бы широко ни использовалось приложение, без разрешения, зафиксированного организацией, оно не увидит ни одной записи. Разрешение имеет дату, область действия и может быть отозвано.
Версионирование
- Версия указывается в путиЭндпоинты публикуются за префиксом версии; сегодняшняя поверхность — первая версия.
- Ломающее изменение открывает новый путьКонтракт существующего эндпоинта не ломается на месте. Несовместимое изменение публикуется по новому пути версии, а прежний продолжает работать.
- Документ сам сообщает свою версиюСправочник несёт номер версии, из которой он сформирован; какую версию вы читаете, отвечает сам документ.
Среды и ограничения
В справочнике объявлены две среды: рабочая и локальная разработка. Корневой адрес передаётся интегратору вместе с ключом; на этой странице он не публикуется.
- Живучесть и готовность измеряются отдельноОдин эндпоинт сообщает, что процесс жив; второй отправляет реальный запрос к базе данных и подтверждает её доступность. Только второй решает, направлять ли трафик.
- Источники браузера ограничены спискомКросс-доменные запросы принимаются только с заранее объявленных источников; пока список пуст, кросс-доменный запрос из браузера отклоняется.
- Ограничение тела запросаТело запроса не может превышать пять мегабайт. Большие наборы передаются как задание массовой передачи с собственной записью состояния, а не одним запросом.
- Секреты в журнал не пишутсяВ журнале сервера не сохраняются ни заголовок авторизации, ни cookie, ни пароль, ни идентификационный номер.
Ограничение частоты
Лимит считается по адресу и по минуте. По умолчанию — 120 запросов в минуту, значение задаётся при развёртывании. Остаток сообщается в заголовках каждого ответа.
| Заголовок ответа | Что он сообщает |
|---|---|
| x-ratelimit-limit | Общая квота внутри окна. |
| x-ratelimit-remaining | Сколько осталось в текущем окне. |
| x-ratelimit-reset | Секунды до обновления квоты. |
| retry-after | Через сколько секунд повторять запрос. Присутствует только в ответе, отклонившем запрос. |
После превышения лимита запрос отклоняется, а в ответе указывается, сколько секунд нужно подождать. Повтор выполняется по истечении этого времени, а не сразу.
Формат ошибки
Любая ошибка возвращается в одной и той же оболочке: короткое поле кода — для ветвления в программе и поле пояснения — для чтения человеком.
- errorКороткий код, по которому клиент принимает решение.
- messageПояснение о том, что произошло.
| Статус | Поле кода | Что это значит |
|---|---|---|
| 400 | Bad Request | Запрос не соответствует схеме. В пояснении указано отсутствующее или неверное поле. |
| 401 | unauthenticated | Действительной личности нет: токен не отправлен, истёк или не прошёл проверку. |
| 404 | Not Found | Такого эндпоинта нет либо такой записи нет. |
| 429 | Too Many Requests | Превышен лимит частоты запросов; в ответе указано, сколько нужно подождать. |
| 5xx | internal_error | Непредвиденный сбой. Подробности клиенту не передаются — они пишутся в журнал сервера. |
Постраничная выдача
Эндпоинты, возвращающие списки, принимают одни и те же два параметра и возвращают одни и те же счётчики, поэтому клиент постраничной выдачи не переписывается под каждый эндпоинт.
- limitСколько записей должно быть на странице. Не менее одной и не более двухсот; при отсутствии значения — пятьдесят.
- offsetСколько записей пропустить. Отсчёт начинается с нуля.
- totalСколько записей всего соответствует фильтрам.
- countСколько записей фактически содержит этот ответ.
В ответе также повторяются использованные limit и offset; клиент читает свою позицию из ответа, а не угадывает её.
Обмен данными и веб-хуки
Режим обмена — это настройка, а не отдельный продукт: каждое зарегистрированное приложение хранит режим своей работы в собственной записи.
| Режим | Что это значит |
|---|---|
| Односторонний — наружу | Optifora публикует данные; другая сторона читает их или подписывается на события. |
| Односторонний — внутрь | Другая сторона отправляет данные; Optifora проверяет их и записывает. |
| Двусторонний | Пишут обе стороны; правило разрешения конфликтов определяется заранее. |
| Рукопожатие | Каждая передача открывает сессию: предложение, проверка, подтверждение, передача и квитанция. Квитанция остаётся у обеих сторон. |
- События отправляются наружуВеб-хук отправляет событие на адрес обратного вызова, объявленный зарегистрированным приложением. Событие, которое не удалось доставить, остаётся в очереди и повторяется; оно никогда не теряется молча.
- Один и тот же запрос не пишется дваждыЗапрос на запись несёт ключ идемпотентности. Второй запрос с тем же ключом не создаёт вторую запись.
- Каждый вызов измеряетсяКто вызвал, когда, с какой областью действия и с каким результатом — всё это фиксируется. Одна и та же запись отвечает и на вопросы отладки, и на вопрос, кто выгрузил эти данные.
- Наши приложения входят в ту же дверьПривилегированного второго пути не существует. Наша собственная интеграция — доказательство того, с какой поверхностью встретится внешний разработчик.
Модель данных для слоя обмена готова; её эндпоинты пока не опубликованы. Когда они появятся, в этом разделе будут ссылки на их статьи в справочнике.
Справочные документы
Справочник не пишется вручную — он формируется из схем эндпоинтов. По мере того как каждый эндпоинт передаёт свою схему, документ заполняется сам, поэтому документ и поведение не могут разойтись.
- Сегодня: в подготовкеСхемы переносятся модуль за модулем. К моменту публикации документа в нём будут видны запрос и ответ каждого эндпоинта.
- Будут опубликованы два форматаМашиночитаемый документ OpenAPI и страница справочника, построенная из того же документа и открываемая в браузере.
- Доступ разделён по уровнямОбзор открыт всем. Полный справочник может находиться за токеном документации, выдаваемым зарегистрированному интегратору; рабочие ключи и адреса обратного вызова — вообще не вопрос документации, они относятся к записи приложения.
- Стандарт адресовПубликуются два справочника с фиксированными адресами: client-api.optifora.com/docs открыт, admin-api.optifora.com/docs требует авторизации и закрыт извне. Сегодня ни один из них не запущен; ссылки появятся в этом разделе, как только они заработают.
Если ваш план интеграции уже готов, напишите нам со страницы контактов: вы узнаете об открытии поверхности одними из первых.
У вас есть конкретный вопрос?
Эти страницы объясняют, как устроен процесс поддержки. Если у вас есть просьба или вопрос, напишите нам со страницы контактов.
Перейти на страницу контактов