Налаштування Magento 2 REST/GraphQL API

Налаштування Magento 2 REST/GraphQL API

Типовий сценарій: CRM потребує push-оновлення залишків, але стандартний /V1/products видає надлишок полів. Або PWA-фронтенд гальмує через N+1 запити до категорій. Ми вирішуємо ці задачі: налаштовуємо аутентифікацію, пишемо кастомні ендпоїнти, впроваджуємо GraphQL. Весь цикл — від аналізу до деплою — займає від 5 до 15 днів. Досвід показує, що правильне налаштування API скорочує час інтеграції в 2–3 рази.

Проблеми, які знімає налаштування API

Аутентифікація та безпека. Часта помилка — неправильно налаштована інтеграція OAuth, яка повертає 401. Ми виставляємо права доступу (Resource Access) так, щоб кожен ендпоінт був доступний строго за роллю. Для внутрішніх сервісів використовуємо token-based (Bearer) — простіше та швидше. Економія часу на налагодження — до 2 днів (Офіційна документація Magento). Гарантія безпеки підтверджується регулярними аудитами.

Продуктивність REST. Без кешування масові операції (наприклад, оновлення 10 000 товарів) викликають таймаути. Рішення — Async REST API (POST /async/V1/products) та Varnish frontend. На публічні ендпоїнти ставимо Nginx-кеш. В результаті TTFB падає в 3–5 разів. На одному з проектів це дозволило знизити навантаження на сервер на 40%. Async REST API дозволяє обробляти масові запити в 5 разів швидше, ніж синхронні. Економія на трафіку сягає $1000 щомісяця.

GraphQL N+1. При запиті товарів з категоріями без DataLoader кожен елемент породжує окремий SQL-запит. Використовуємо Batch-розв'язувачі та агрегуємо вибірку. GraphQL у такому сценарії швидше REST в 2–3 рази за обсягом відповіді. Економія трафіку до 40%. Для PWA-фронтенду це особливо критично — сторінки завантажуються за 1–2 секунди.

Чому варто обрати кастомний ендпоінт?

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

interface ProductStatsInterface {
    public function getStats(string $sku): array;
}

У класі інжектимо ProductRepositoryInterface та StockRegistryInterface. Повертаємо ціну, кількість, статус наявності. Маршрут налаштовується в etc/webapi.xml. Один ендпоінт замість двох — менше трафіку та швидше розробка. Кастомний ендпоінт краще стандартного в 2 рази за швидкістю отримання даних.

Як налаштувати аутентифікацію для зовнішніх сервісів?

Для зовнішніх сервісів (CRM, ERP) використовуємо OAuth 1.0a. У панелі адміністратора створюється інтеграція, генеруються Consumer Key/Secret та Access Token/Secret. Кожен запит підписується, що забезпечує високу безпеку. Для внутрішніх інтеграцій достатньо token-based: POST /V1/integration/admin/token повертає токен, дійсний 1 годину. Якщо потрібно більше — налаштовуємо refresh-токени.

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

1. Аналітика — виявляємо вузькі місця: повільні запити, надлишкові дані, невірні ролі.
2. Проектування — обираємо протокол (REST/GraphQL), проектуємо схему ендпоінтів, пишемо тести.
3. Реалізація — пишемо модулі, налаштовуємо ACL, оптимізуємо запити. Для масових операцій — Async API з RabbitMQ.
4. Тестування — навантаження JMeter, перевірка Core Web Vitals (LCP, TTFB). Переконуємось, що API витримує 1000 RPS.
5. Деплой — розгортаємо з Varnish та Redis, передаємо Postman-колекцію та GraphQL-схему, навчаємо команду.

Уникнення rate limiting при масових операціях

Для інтеграцій з великим обсягом (наприклад, завантаження 10 000 товарів) використовуємо Bulky API: відправляємо запит на /async/V1/products з масивом товарів. Magento обробляє їх асинхронно, не блокуючи потік. Якщо потрібен зворотній зв'язок — підписуємось на чергу product_action_notification. Так ми обходимо ліміти та зберігаємо продуктивність. Це рішення перевірено на проектах з 50 000+ товарів.

Порівняння REST та GraphQL

Порівняння методів аутентифікації

Дані підтверджені офіційною документацією Magento.

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

• Налаштування аутентифікації (Token/OAuth) та ACL.
• Розробка кастомних REST/GraphQL ендпоінтів під бізнес-логіку.
• Оптимізація продуктивності: кешування, асинхронні черги, DataLoader.
• Документація API (Postman, GraphQL schema) та навчання команди.
• Гарантія сумісності з останніми версіями Magento та PHP 8.2+.
• Підтримка після деплою: моніторинг, фікси rate limiting, доробки.

Вартість базового налаштування аутентифікації — від $200, створення одного кастомного ендпоінта — від $500. Економія на трафіку сягає $1000 щомісяця. Орієнтовні терміни — від 5 до 15 днів. Вартість розраховується індивідуально після аналізу проекту. Наша компанія має 8+ років досвіду з Magento та 30+ реалізованих інтеграцій. Залиште заявку — оцінимо проект за 1 день. Зв'яжіться з нами для консультації — наші інженери допоможуть обрати спосіб інтеграції та оптимізувати ваш API. Замовте налаштування API Magento 2 — ми гарантуємо продуктивність та безпеку. GraphQL краще REST в 2-3 рази за обсягом відповіді, а кастомний ендпоінт краще стандартного в 2 рази за швидкістю отримання даних.

Приклад налаштування OAuth: У Magento Admin: Stores → Configuration → Services → OAuth. Вкажіть Consumer Key та Consumer Secret, згенеруйте Access Token. Приклад запиту з підписом: GET /rest/V1/products?oauth_consumer_key=...&oauth_signature=.... Детальніше: OAuth інтеграція Magento.

Офіційна документація: REST API Magento.

Розробка 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 тижнів. Вартість розраховується індивідуально після аудиту. Отримайте консультацію — зв'яжіться з нами, щоб обговорити ваш проект.