API-warmer’и

Тримайте REST- і GraphQL-ендпоїнти теплими — зі справжніми методами, заголовками, куками, тілами запитів і матрицями конфігурації.

13 min read

API охолоджуються так само, як і веб-сторінки. Якщо відповідь JSON є дорогою для створення та кешується у вашому CDN або шлюзі, перший клієнт після закінчення терміну дії сплачує той самий штраф, що й відвідувач веб-сайту.

API warmers вирішує це. Вони керуються окремо від веб-сайту warmers, у розділі Обліковий запис → API Warmers, і мають власні обмеження плану.

Окремо від сайту warmers

Підігрівачі API є окремою особливістю з власним правом.Якщо розділ відсутній або заблокований, ваш план їх не включає — див. Плани та обмеження.

Коли використовувати один

Ситуація	Чому API warmer допомагає
Безголовий магазин або сайт	JSON продукту, асортименту та вмісту отримується під час візуалізації кожної сторінки. Зігрівання цих маршрутів забезпечує швидкий весь передній кінець.
Загальнодоступний API розробника	Популярні кінцеві точки та приклади документації залишаються чуйними, а не повільними для тих, хто дзвонить першим.
Рівень «backend-for-frontend».	Об’єднані кінцеві точки, які розходяться на кілька служб, дорого відновлювати. Утеплення їх захищає мобільні та веб-клієнти.
Важкі GraphQL операції	Зазвичай трафік домінує кілька запитів. Потепління цих конкретних операцій має набагато більше значення, ніж одноразове натискання `/graphql`.

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

Створення API warmer

1
Перевірити API hostname
URL-адреси кінцевих точок мають використовувати перевірений hostname, точно як веб-сайт warmers. Див. Hostname перевірка.
2
Назвіть warmer і залиште його неактивним
Спочатку налаштуйте, активуйте, коли будете задоволені.
3
Додайте одну або кілька кінцевих точок
Кожна кінцева точка має URL-адресу та метод HTTP, а також, за бажанням, мітку, тіло та тип вмісту.
4
Додайте авторизацію, якщо це потрібно кінцевій точці
Глобальні заголовки та файли cookie застосовуються до кожного запиту, який робить warmer.
5
За бажанням можна розширити за допомогою матриці конфігурації
Охоплюйте багато варіантів — локалі, орендарі, ідентифікатори — без створення десятків майже ідентичних warmers.
6
Встановіть швидкість і інтервали, потім активуйте
Така сама ідея, як на веб-сайті warmers: нагрівайте досить часто, щоб перевищити TTL вашого кешу, досить повільно, щоб не зашкодити.

Кінцеві точки

Кожна кінцева точка в warmer конфігурується незалежно:

Мітка: Необов’язкова зрозуміла людині назва, тому довгий список кінцевих точок залишається читабельним.
URL: Повна адреса кінцевої точки на перевіреному hostname. Може містити заповнювачі шляху, як-от {id} або :id, у поєднанні з розміром PATH.
метод: GET, POST та інші залежно від вашого плану. Плани зазвичай дозволяють GET і HEAD за умовчанням, з більшою кількістю методів на вищих рівнях.
Протокол: REST або GRAPHQL. Якщо вибрати GraphQL, відкриються поля операції та запиту.
Шаблон тіла запиту: Тіло для відправки, для методів, які несуть один. Потрібне дозвіл тіла запиту API.
Тип вмісту: Тип вмісту тіла запиту, зазвичай application/json.
Ідемпотент: Позначає кінцеву точку як безпечну для виклику двічі, увімкнувши холодну/теплу подвійну вибірку, яка вимірює покращення. Увімкніть його лише тоді, коли дзвоните двічі, справді не має побічних ефектів.
Увімкнено: Чи включена ця конкретна кінцева точка в цикли. Зручно для тимчасового вимкнення однієї кінцевої точки без її видалення.

Будьте обережні, позначаючи операції запису ідемпотентними

Подвійна вибірка на кінцевій точці, яка створює замовлення, надсилає електронну пошту або стягує плату з карток, зробить це двічі. Позначайте кінцеву точку ідемпотентом лише тоді, коли її повторення справді нешкідливо.

Конфігураційні матриці

Більшість API мають варіанти: одна і та сама кінцева точка, що викликається для кожного регіону, кожного клієнта, валюти чи ідентифікатора. Створення warmer для кожного неможливе.

Матриця конфігурації вирішує це. Ви визначаєте розміри з кількома значеннями, а Cache Rocket розширює повний декартовий добуток на окремі теплі запити.

Тип розміру	Вводить значення в	приклад
`QUERY`	Рядок запиту	`locale=en`, `locale=nl`, `locale=de`
`HEADER`	Заголовок запиту	`X-Tenant: acme`, `X-Tenant: globex`
`COOKIE`	Печиво	`currency=EUR`, `currency=USD`
`PATH`	`{placeholder}` в URL-адресі	`{id}` → `1`, `2`, `3`

Спрацьований приклад

text

Endpoint:  GET https://api.example.com/v1/products/{category}

Dimensions:
  PATH   category = shoes, bags, hats
  QUERY  locale   = en, nl

Expands to 6 warm requests:
  /v1/products/shoes?locale=en
  /v1/products/shoes?locale=nl
  /v1/products/bags?locale=en
  /v1/products/bags?locale=nl
  /v1/products/hats?locale=en
  /v1/products/hats?locale=nl

Комбінації швидко множаться

Загальна кількість запитів є добутком кількості значень кожного параметра. Три виміри з п’яти значень у кожному — це 125 комбінацій з однієї кінцевої точки. Форма показує поточну кількість і максимум вашого плану — спостерігайте за цим, додаючи значення.

Якщо ви перевищите максимум плану, warmer не збереже. Зменште значення, розділіть на кілька warmers або оновіть.

Аутентифікація

Глобальні заголовки запитів і файли cookie застосовуються до кожного варіанту, який створює warmer. Сюди йде заголовок Authorization або сеансовий файл cookie.

Типові заголовки авторизації

text

Authorization: Bearer YOUR_LONG_LIVED_TOKEN
X-Api-Key: YOUR_API_KEY

Підігрійте варіант, який насправді запитують реальні клієнти

Якщо ваш кеш змінюється на Authorization, підігрів за допомогою службового маркера заповнює запис кешу, який має ключ до цього маркера, — якого реальний клієнт ніколи не потрапить. Для спільних кешованих відповідей розігрівайте так само, як звичайний клієнт викликає кінцеву точку.

Термін дії токенів закінчується. Якщо API warmer раптом починає повертати 401, жорстко закодований маркер – це перше, що потрібно перевірити.

GraphQL

GraphQL потребує окремого лікування, оскільки продуктивність залежить від конкретної операції, а не від шляху кінцевої точки. Натискання /graphql один раз нічого не скаже; розігрівання ваших трьох найважчих запитів говорить вам усе.

Установіть протокол кінцевої точки на GraphQL, а потім укажіть:

Операція GraphQL — query чи mutation. Потепління мутацій майже ніколи не є доречним.
GraphQL запит — документ операції для надсилання.
Змінні — надайте їх через шаблон тіла запиту або як значення розмірності матриці, щоб зігріти кілька наборів змінних.

Note

Потепління GraphQL регулюється власним планом надання послуг на додаток до API warmers.

Імпорт OpenAPI

У підтримуваних планах ви можете імпортувати кінцеві точки безпосередньо зі специфікації OpenAPI 3 замість того, щоб вводити їх. Вставте URL-адресу специфікації JSON або YAML і натисніть Імпортувати; виявлені кінцеві точки додаються до warmer, готові до скорочення та налаштування.

Tip

Імпорт містить усе, що описує специфікація, включно з операціями запису. Уважно перегляньте список і перед активацією вимкніть усе, що не слід викликати за розкладом.

Ліміти та планування

Максимальний нагрів за хвилину: Межа тарифів для цього API warmer, що еквівалентно максимальній кількості URL-адрес за хвилину на веб-сайті warmer.
Час очікування запиту: Як довго чекати відповіді, перш ніж здатися.
Інтервал автозапуску: Як часто починається новий теплий прохід, у секундах.
Інтервал постановки в чергу: Темп роботи з повторним чергуванням у межах циклу.
Переписати на HTTPS: Оновіть URL-адреси кінцевих точок http:// до https://.
Теплий графік: Вікна пікового та позапікового навантаження, той самий формат JSON, що й підігрівачі веб-сайтів.Див. Розширений розігрів.

Ваш план також обмежує кількість API warmers, кінцевих точок на warmer та комбінацій на warmer.

Загальні проблеми

Все повертає 401 або 403.: Заголовок авторизації або файл cookie відсутній, неправильний або термін дії минув. Звичайним винуватцем є довгоживучі токени — перевірте, чи токен досі дійсний і чи не змінився.
warmer не збереже, посилаючись на забагато комбінацій.: Ваша матриця розширюється за межі планового максимуму. Зменште значення розмірів, розділіть кінцеві точки на кілька warmers або оновіть.
Мені потрібного методу немає в спадному меню.: Плани обмежують дозволені методи HTTP. Нижні рівні зазвичай дозволяють лише GET та HEAD.
Розігрів працює добре, але реальні клієнти реагують повільно.: Ймовірно, ви заповнюєте інший варіант кешу, ніж запит клієнта — зазвичай через заголовок Authorization, файл cookie або заголовок, який залежить від вашого CDN. Порівняйте точний запит, який надсилає реальний клієнт, із тим, що надсилає warmer.
Чи можу я зігріти кінцеву точку, для якої потрібен підписаний короткочасний маркер?: Ненадійно, тому що warmer не може створити новий підпис за один запуск. Або викрийте кешований неавтентифікований варіант, або використовуйте довготривалий маркер служби, де це безпечно.