Як працює 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 потребує авторизації і закритий назовні. Сьогодні жоден із них не працює; посилання буде додано до цього розділу, щойно вони запрацюють.
Якщо ваш план інтеграції вже сформовано, напишіть нам зі сторінки контактів: ви одними з перших дізнаєтеся про відкриття поверхні API.
Маєте конкретний запит?
Ці сторінки пояснюють, як влаштовано процес підтримки. Якщо у вас є запит або запитання, напишіть нам зі сторінки контактів.
Перейти на сторінку контактів