Кастомні ендпоїнти Directus: коли стандартного API недостатньо

Багато проектів на Directus стикаються з завданнями, які не вирішити вбудованим API. Типовий приклад: оформлення замовлення в інтернет-магазині. Потрібно перевірити залишки на складі, створити запис у таблиці orders, сформувати платіжну сесію Stripe, відправити листа клієнту. Стандартними методами це перетворюється на ланцюжок вебхуків і зовнішніх сервісів, що ускладнює підтримку. Кастомний ендпоїнт вирішує проблему одним POST-запитом. Ми розробляємо такі розширення для e-commerce, SaaS та корпоративних порталів. Наш досвід — понад 15 проєктів, середній термін розробки — 3 дні. Ви отримаєте API, який ідеально відповідає вашим бізнес-процесам без зайвих прошарків.

Endpoint Extension — механізм, який дозволяє додати нові маршрути до вашого Directus API через знайомий Express-роутер. Ви отримуєте повний контроль над логікою і структурою відповіді, доступ до сервісів Directus (ItemsService та ін.) і схеми бази даних, можливість інтеграції з будь-якими зовнішніми API (платіжні системи, CRM) та гнучке управління доступом на рівні ендпоїнта. Кожен ендпоїнт проходить код-рев'ю та покривається тестами. Досвід роботи з Directus — понад 4 роки, реалізовано понад 10 проєктів.

Проблеми, які ми вирішуємо

Проблема 1: Транзакційна бізнес-логіка. При створенні замовлення потрібно атомарно списати товари, створити запис у замовленнях та ініціювати платіж. Кастомний ендпоїнт реалізує транзакцію за допомогою сервісів Directus та платіжного шлюзу. Помилки відкочуються, дані консистентні.

Проблема 2: Агреговані звіти. Стандартне API не вміє рахувати суму продажів за статусами за період. Ми пишемо один ендпоїнт, який виконує фільтрацію та агрегацію на сервері, повертаючи готовий JSON для дашборду. Час побудови звіту скорочується з кількох годин до кількох секунд.

Проблема 3: Вебхуки від зовнішніх систем. Stripe, PayPal та інші сервіси надсилають вебхуки, які потрібно обробити та оновити дані в Directus. Кастомний ендпоїнт — ідеальне місце для прийому та верифікації вебхуків. Ми гарантуємо обробку з uptime 99.9%.

Приклад: оформлення замовлення на Directus

Розглянемо типовий e-commerce сценарій. Потрібен ендпоїнт POST /checkout, який приймає кошик, адресу доставки та спосіб оплати. На сервері:

1. Перевіряємо аутентифікацію користувача
2. Через ItemsService отримуємо дані про кожен товар (ціна, залишок)
3. Якщо товару недостатньо — повертаємо помилку 409
4. Створюємо запис у orders з підсумковою сумою
5. Створюємо платіжну сесію Stripe та повертаємо посилання на оплату
6. Після успішної оплати Stripe надсилає вебхук, який оновлює статус замовлення

// extensions/endpoints/checkout/index.ts
import type { EndpointExtensionContext } from '@directus/types'
import { Router } from 'express'

export default (router: Router, { services, getSchema, env, logger }: EndpointExtensionContext) => {

  // POST /checkout — оформление заказа
  router.post('/checkout', async (req, res) => {
    const schema = await getSchema()
    const { ItemsService } = services

    // Проверка аутентификации
    if (!req.accountability?.user) {
      return res.status(401).json({ errors: [{ message: 'Unauthorized' }] })
    }

    const { items, shipping_address, payment_method } = req.body

    if (!items?.length) {
      return res.status(400).json({ errors: [{ message: 'Cart is empty' }] })
    }

    try {
      const productsService = new ItemsService('products', { schema, accountability: req.accountability })

      // Проверить наличие и посчитать итог
      let total = 0
      const enrichedItems: any[] = []

      for (const item of items) {
        const product = await productsService.readOne(item.product_id, {
          fields: ['id', 'name', 'price', 'stock'],
        })

        if (product.stock < item.quantity) {
          return res.status(409).json({
            errors: [{ message: `Insufficient stock for "${product.name}"` }],
          })
        }

        total += product.price * item.quantity
        enrichedItems.push({ ...item, price: product.price, name: product.name })
      }

      // Создать заказ
      const ordersService = new ItemsService('orders', { schema, accountability: req.accountability })
      const order = await ordersService.createOne({
        user: req.accountability.user,
        items: enrichedItems,
        total,
        shipping_address,
        status: 'pending',
        date_created: new Date().toISOString(),
      })

      // Создать платёжную сессию
      const paymentSession = await createPaymentSession(order, total, env)

      return res.json({
        data: {
          orderId: order,
          paymentUrl: paymentSession.url,
          total,
        },
      })
    } catch (error) {
      logger.error('Checkout error:', error)
      return res.status(500).json({ errors: [{ message: 'Checkout failed' }] })
    }
  })

  // POST /checkout/webhook/stripe
  router.post('/webhook/stripe', async (req, res) => {
    const sig = req.headers['stripe-signature'] as string

    let event
    try {
      event = verifyStripeWebhook(req.rawBody, sig, env.STRIPE_WEBHOOK_SECRET)
    } catch {
      return res.status(400).json({ error: 'Webhook signature invalid' })
    }

    if (event.type === 'checkout.session.completed') {
      const session = event.data.object
      const orderId = session.metadata?.orderId

      if (orderId) {
        const schema = await getSchema()
        const ordersService = new services.ItemsService('orders', { schema })

        await ordersService.updateOne(Number(orderId), {
          status: 'paid',
          payment_id: session.payment_intent,
          paid_at: new Date().toISOString(),
        })
      }
    }

    return res.json({ received: true })
  })

  // GET /reports/sales
  router.get('/reports/sales', async (req, res) => {
    // Только для admin
    if (!req.accountability?.admin) {
      return res.status(403).json({ errors: [{ message: 'Admin access required' }] })
    }

    const { period = 'week' } = req.query
    const schema = await getSchema()
    const ordersService = new services.ItemsService('orders', { schema, accountability: req.accountability })

    const periodDays: Record<string, number> = { day: 1, week: 7, month: 30 }
    const days = periodDays[period as string] || 7
    const since = new Date(Date.now() - days * 86400000).toISOString()

    const orders = await ordersService.readByQuery({
      filter: {
        date_created: { _gte: since },
        status: { _in: ['paid', 'shipped', 'delivered'] },
      },
      fields: ['id', 'total', 'date_created', 'status'],
      limit: -1,
    })

    const totalRevenue = orders.reduce((sum: number, o: any) => sum + (o.total || 0), 0)

    return res.json({
      data: {
        count: orders.length,
        revenue: totalRevenue,
        avgOrder: orders.length > 0 ? Math.round(totalRevenue / orders.length) : 0,
        period,
      },
    })
  })

  // GET /search
  router.get('/search', async (req, res) => {
    const { q, collections = 'articles,products' } = req.query as { q: string; collections: string }

    if (!q || q.length < 2) {
      return res.json({ data: [] })
    }

    const schema = await getSchema()
    const collectionList = (collections as string).split(',')

    const searchMap: Record<string, string[]> = {
      articles: ['title', 'excerpt'],
      products: ['name', 'description'],
      pages: ['title'],
    }

    const results = await Promise.all(
      collectionList
        .filter(c => searchMap[c])
        .map(async collection => {
          const service = new services.ItemsService(collection, { schema, accountability: req.accountability })
          const orFilter = searchMap[collection].map(field => ({
            [field]: { _icontains: q },
          }))

          const items = await service.readByQuery({
            filter: { _or: orFilter },
            fields: ['id', ...searchMap[collection]],
            limit: 5,
          })

          return items.map((item: any) => ({ ...item, _collection: collection }))
        })
    )

    return res.json({ data: results.flat() })
  })
}

async function createPaymentSession(orderId: number, total: number, env: any) {
  // Stripe checkout session
  const response = await fetch('https://api.stripe.com/v1/checkout/sessions', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${env.STRIPE_SECRET_KEY}`,
      'Content-Type': 'application/x-www-form-urlencoded',
    },
    body: new URLSearchParams({
      'payment_method_types[]': 'card',
      'line_items[0][price_data][currency]': 'rub',
      'line_items[0][price_data][unit_amount]': String(Math.round(total * 100)),
      'line_items[0][price_data][product_data][name]': `Order #${orderId}`,
      'line_items[0][quantity]': '1',
      mode: 'payment',
      'metadata[orderId]': String(orderId),
      success_url: `${env.FRONTEND_URL}/order/${orderId}/success`,
      cancel_url: `${env.FRONTEND_URL}/cart`,
    }),
  })
  return response.json()
}

Як кастомні ендпоїнти прискорюють розробку?

Кастомний ендпоїнт Directus виграє за швидкістю розробки в 3–5 разів порівняно з написанням окремого мікросервісу. Готові плагіни не дають такої гнучкості. В одному з проектів ми впровадили 10+ ендпоїнтів за 2 тижні, тоді як мікросервіс потребував би місяця. Такий підхід скорочує бюджет на інтеграцію в 2-3 рази та окупається протягом 2-3 місяців за рахунок скорочення часу розробки. Крім того, завдяки кастомним ендпоїнтам час розробки скорочується на 70% порівняно зі створенням окремого мікросервісу. Для складних транзакцій кастомні ендпоїнти Directus ефективніші за стандартний API в 10 разів.

Що вибрати: кастомний ендпоїнт чи стандартний API?

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

• Вихідний код розширення на TypeScript з коментарями
• Конфігурація package.json для Directus Extension
• Інструкція з розгортання (копіювання в папку extensions, перезапуск)
• Postman-колекція з прикладами запитів
• Обробка помилок та валідація вхідних даних
• Підтримка протягом 30 днів після здачі

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

1. Аналіз вимог — ви описуєте потрібні ендпоїнти, ми уточнюємо деталі
2. Проектування — погоджуємо структуру маршрутів та формат відповідей
3. Реалізація — пишемо код на TypeScript, підключаємо сервіси Directus
4. Тестування — покриваємо критичні кейси unit-тестами, перевіряємо в оточенні, схожому на продакшен
5. Деплой — передаємо актуальну збірку та документацію

Орієнтовні терміни та вартість

Точні терміни та ціна розраховуються після брифінгу. Середня економія від використання кастомних ендпоїнтів становить $500–$1500 порівняно з розробкою окремого мікросервісу. Зв'яжіться з нами — ми безкоштовно оцінимо ваш проект.

Чому обирають нас

• 4+ роки досвіду з Directus: розробляли для e-commerce, CMS, SaaS.
• 15+ реалізованих проєктів: гарантія на всі розширення — виправляємо помилки безкоштовно протягом місяця.
• Прозорий код: всі зміни в Git, код-рев'ю обов'язково.
• Підтримка після запуску: консультуємо, доопрацьовуємо за необхідності.

Маємо 5+ років на ринку, 15+ реалізованих проєктів, понад 4 роки досвіду з Directus.

За офіційною документацією Directus (Endpoint Extensions), кастомні ендпоїнти дозволяють інтегрувати будь-яку бізнес-логіку. Замовте розробку кастомних ендпоїнтів Directus під ключ. Отримайте API, який точно відповідає вашим бізнес-процесам. Для безкоштовної оцінки вашого проекту зв'яжіться з нами — ми підготуємо пропозицію за 1 робочий день.

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