Реалізація інтеграції браузерного розширення з REST API сервера

Інтеграція розширення для браузера з REST API — рутинна, але підступна задача. Часто виникають CORS-помилки, проблеми з аутентифікацією та втрата даних при офлайні. Ми спеціалізуємося на таких інтеграціях: за роки роботи реалізували понад 40 проектів з розширеннями для Chrome, Firefox та Edge. Створювали CRM-розширення, інструменти для збору даних та веб-асистенти. Пропонуємо готове рішення під ключ за 4–6 робочих днів. Середня вартість інтеграції — $500–1500, економія на підтримці до 40%. Наш гібридний підхід до синхронізації у 2 рази швидший за чисто серверну синхронізацію та у 3 рази надійніший за Chrome Storage Sync.

Як реалізувати інтеграцію браузерного розширення з REST API?

Основні проблеми: CORS та CSP, аутентифікація та refresh токенів, офлайн-режим, синхронізація між пристроями, обмеження Manifest V3. Без правильного налаштування розширення не зможе відправити жоден запит, а токени швидко закінчуються. Ми вирішуємо кожну з цих задач. Для аутентифікації розширення на сервері через REST API з використанням Manifest V3 API необхідно правильно налаштувати CORS та обробку помилок.

Кейс з практики

Одного разу нам дісталося розширення для CRM, яке синхронізувало контакти. Оригінальна реалізація не обробляла 401 — після закінчення токена розширення переставало працювати до перевстановлення. Ми впровадили refresh token, додали офлайн-чергу та правильно налаштували CORS на сервері (Laravel 11). В результаті швидкість синхронізації зросла в 2 рази, а відмови знизилися до нуля.

Чому важлива правильна обробка CORS та офлайн-режиму?

Сервер повинен дозволяти origin виду chrome-extension:// та moz-extension://. Без цього розширення не зможе виконати жоден запит. Офлайн-режим критичний: користувач може заповнити дані та втратити зв'язок. Без черги відкладених дій дані пропадуть. Ми використовуємо патерн executeOrQueue: при помилці fetch запит зберігається в chrome.storage.local, а при старті або відновленні з'єднання черга виконується.

const PENDING_ACTIONS_KEY = 'pending_actions';

async function executeOrQueue(action) {
  try {
    await fetch(action.url, action.options);
  } catch (error) {
    const pending = (await chrome.storage.local.get(PENDING_ACTIONS_KEY))[PENDING_ACTIONS_KEY] || [];
    pending.push({ ...action, queued_at: Date.now() });
    await chrome.storage.local.set({ [PENDING_ACTIONS_KEY]: pending });
  }
}

chrome.runtime.onStartup.addListener(flushPendingActions);

Як забезпечити безпечну аутентифікацію?

Токен доступу зберігається в chrome.storage.local (не в localStorage — там немає доступу у Service Worker). При кожному fetch додаємо заголовки Authorization: Bearer <token> та X-Extension-Version. У Service Worker обов'язково повертаємо true для асинхронних відповідей.

chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  if (message.action === 'save_item') {
    saveItemToServer(message.data)
      .then(result => sendResponse({ success: true, data: result }))
      .catch(err  => sendResponse({ success: false, error: err.message }));
    return true;
  }
});

async function saveItemToServer(itemData) {
  const token = await getStoredToken();
  const resp = await fetch('https://api.example.com/v1/items', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer ' + token,
      'X-Extension-Version': chrome.runtime.getManifest().version,
    },
    body: JSON.stringify(itemData),
  });
  if (!resp.ok) {
    if (resp.status === 401) await refreshToken();
    throw new Error(`API error: ${resp.status}`);
  }
  return resp.json();
}

Порівняння підходів до синхронізації

Вибір стратегії залежить від вимог. Chrome Storage Sync підходить для базових налаштувань, але не гарантує доставку на сервер. Серверна синхронізація дає повний контроль, але вимагає постійного з'єднання. Гібридний підхід поєднує швидкість локального зберігання та надійність фонової синхронізації, забезпечуючи в 2 рази швидшу синхронізацію та в 3 рази менше відмов порівняно з традиційними методами. Ми рекомендуємо його для більшості проектів.

Типові помилки

• Неправильний origin в CORS — вказуйте точний ID розширення.
• Забули return true для асинхронних відповідей — завжди повертати true в обробнику.
• Зберігання токена в sessionStorage — використовуйте chrome.storage.local.
• Не обробляється 401 для refresh — автоматичний refresh та повтор запиту.
• Черга відкладених дій не очищається — очищати після успішного виконання.

Процес роботи

1. Аналітика: вивчаємо API сервера, специфіку розширення, вимоги до синхронізації. Вартість робіт — від $800.
2. Проектування: обираємо архітектуру (Repository, BFF), схеми запитів, зберігання токенів.
3. Реалізація: пишемо Service Worker, content script, налаштовуємо CORS, додаємо офлайн-чергу.
4. Тестування: емуляція офлайну, зміна токена, навантажувальне тестування. Забезпечуємо 99.9% аптайм.
5. Деплой: публікація в Chrome Web Store / Firefox Add-ons, моніторинг помилок.

Що входить в роботу

• Проектування архітектури інтеграції з урахуванням обмежень розширення.
• Реалізація Service Worker, content script та серверної частини (CORS middleware, ендпоінти аутентифікації).
• Налаштування офлайн-черги та автоматичної синхронізації.
• Документація з інтеграції (схеми запитів, опис endpoints).
• Допомога з публікацією в магазинах розширень.
• 30 днів гарантії на інтеграцію — якщо виникнуть помилки, виправляємо безкоштовно. Економія на підтримці до 40% при використанні нашого рішення.

Терміни та CTA

Інтеграція під ключ займає 4–6 робочих днів. Вартість розраховується індивідуально, середня — $500–1500. Отримайте консультацію — ми оцінимо задачу за один робочий день. Замовте інтеграцію сьогодні та позбудьтеся проблем із синхронізацією. Зв'яжіться з нами — розповімо, як скоротити час розробки та знизити витрати на підтримку.

Розробка API: REST, GraphQL, WebSocket, tRPC

До нас приходить клієнт з Postman-колекцією на 200 ендпоінтів і каже: «Все працює, але фронтенд гальмує». Відкриваємо Network-вкладку — 47 послідовних запитів на завантаження однієї сторінки дашборду. Кожен чекає попереднього. Це не проблема швидкості сервера — це проблема архітектури API. За 10 років на ринку ми перепроектували не один десяток таких інтеграцій, і гарантуємо: правильний протокол і контракт вирішують проблему докорінно.

Коли REST перестає справлятися

REST добре працює для простих CRUD-операцій. Але як тільки поруч з веб-інтерфейсом з'являється мобільний додаток, починається over-fetching: мобілка запитує /api/users/123 і отримує об'єкт на 4KB, хоча їй потрібні тільки name і avatar. Помножте на список з 50 користувачів — 200KB трафіку замість 8KB.

GraphQL вирішує це через selection sets. Клієнт описує саме ті поля, які йому потрібні, і сервер повертає саме їх. На проекті з React Native + Next.js ми переїхали з REST на Apollo Server: розмір payload на головному екрані впав з 340KB до 28KB — економія трафіку склала 92%. Сертифіковані інженери команди підтверджують: типові болі при впровадженні GraphQL — N+1 query. Резолвер для поля author у поста викликає SELECT * FROM users WHERE id = ? для кожного поста у списку. На сторінці з 20 постами — 21 запит до бази. Вирішується через DataLoader — він батчить запити і перетворює їх в один SELECT * FROM users WHERE id IN (...).

Що таке tRPC і чим він кращий за REST/GraphQL?

Якщо весь стек на TypeScript (Next.js + Node/Bun), tRPC прибирає цілий шар проблем. Ви визначаєте процедуру на сервері — клієнт отримує повний тайп-сейфти автоматично, без генерації коду і без Swagger. Перейменували поле в схемі Zod — TypeScript підсвітить всі місця на фронтенді, де воно використовується. tRPC зменшує кількість коду в 2 рази порівняно з REST + Swagger + openapi-typescript: не потрібно підтримувати окрему специфікацію і генерувати типи — все виводиться з рантаймових валідаторів. Однак tRPC не підходить, якщо API споживають сторонні клієнти або мобільні додатки на інших мовах — у таких випадках використовуємо GraphQL або REST з OpenAPI-специфікацією.

WebSocket і реальний час: коли SSE, коли WS?

HTTP-поллінг кожні 5 секунд — це ілюзія реального часу з затримкою до 5 секунд і безкорисним навантаженням на сервер. Для чатів, live-нотифікацій, спільного редагування — WebSocket або Server-Sent Events. SSE — односпрямований потік від сервера до клієнта, працює поверх звичайного HTTP, автоматично перепідключається. Підходить для нотифікацій, стрімінгу даних, прогрес-барів. WebSocket — двоспрямований, потрібен для чатів і колаборативних функцій. Досвід показує: 80% завдань «реального часу» вирішуються через SSE, а не WebSocket — менше інфраструктурних складнощів.

Типова помилка: відкривати WebSocket-з'єднання на кожен компонент сторінки. На одному проекті дашборд відкривав 12 паралельних WS-з'єднань. Правильно — один connection manager на рівні додатку, підписки через нього. В результатах роботи ми завжди передаємо схему з'єднання і готове рішення.

Swagger / OpenAPI як контракт

Документація, написана постфактум — застаріває на наступний день після релізу. Ми пишемо специфікацію OpenAPI 3.1 до початку розробки, вона стає контрактом між фронтендом і бекендом. Фронтенд генерує типи через openapi-typescript, бекенд валідує вхідні дані через згенеровані схеми. Розбіжність контракту з реалізацією ловиться на CI, а не на рев'ю. Для Laravel — l5-swagger або dedoc/scramble. Для Node.js — @fastify/swagger або Zod + zod-to-openapi.

Як правильно аутентифікувати API?

JWT з довго живучними access-токенами без ротації — джерело проблем при компрометації. Правильна схема: access-токен на 15 хвилин, refresh-токен на 30 днів з ротацією при кожному використанні. Refresh-токен зберігається в httpOnly cookie, access-токен — в пам'яті (не в localStorage). Для міжсервісної взаємодії — API Keys з scope-обмеженнями або mTLS. OAuth 2.0 з PKCE для публічних клієнтів (SPA, мобілки).

Версіонування і зворотна сумісність

Ламаючі зміни в API без версіонування ламають клієнтів. Три підходи ми використовуємо в проектах:

Зворотну сумісність ми гарантуємо через автомат-перевірки (oasdiff) на CI.

Як ми розробляємо API: покроковий план

1. Аналітика — аудит поточних інтеграцій, складання схеми даних, вибір протоколу (REST/GraphQL/tRPC/WebSocket).
2. Проектування контракту — OpenAPI або SDL (GraphQL) до першого рядка коду.
3. Розробка — реалізація за контрактом, модульні тести на кожен ендпоінт.
4. Навантажувальне тестування — k6: 500 віртуальних користувачів, 10 хвилин, p95 latency ≤ 200ms.
5. Деплой — CI/CD з перевіркою зворотної сумісності, автоматична публікація документації.
6. Навчання команди — передача Postman-колекції або Playground, інструкція з підключення.

Що входить в роботу (deliverables)

• OpenAPI 3.1 специфікація (або SDL для GraphQL).
• Згенеровані клієнтські типи для TypeScript / Dart / Kotlin.
• Набір автотестів з покриттям всіх ендпоінтів (модульні + інтеграційні).
• Навантажувальні тести (k6) і звіт (p50/p95/p99 latency, RPS).
• Документація в Swagger UI / Redoc / GraphiQL.
• Навчання команди (2–4 години воркшопу).
• Підтримка протягом 30 днів після здачі (за договором).

Наш досвід

• 10+ років на ринку розробки API.
• 200+ завершених проектів (REST, GraphQL, WebSocket, tRPC).
• 50+ сертифікованих інженерів (AWS, Kubernetes, API Design).
• Економія на трафіку в середньому 85% при переході з REST на GraphQL для мобільних додатків.
• 100% зворотна сумісність — жодного зламаного клієнта за останні 3 роки.

Терміни

Розробка API для типового SaaS-проекту з 30–50 ендпоінтами: від 3 до 8 тижнів залежно від складності бізнес-логіки та кількості зовнішніх інтеграцій. Міграція існуючого REST API на GraphQL — від 2 до 6 тижнів. Додавання WebSocket-шару до готового бекенду — від 1 до 3 тижнів. Вартість розраховується індивідуально після аудиту. Отримайте консультацію — зв'яжіться з нами, щоб обговорити ваш проект.