Настройка Directus REST API / GraphQL API

Настройка Directus REST API / GraphQL API

Directus генерирует полный REST API и GraphQL для всех коллекций автоматически. REST — по умолчанию, GraphQL — включается в настройках. Оба используют одну систему прав доступа.

REST API

Базовые операции:

# Список
GET /items/articles?fields=id,title,slug&filter[status][_eq]=published&sort=-date_published&limit=10

# Один элемент
GET /items/articles/42?fields=*,author.*,category.*

# Создать
POST /items/articles
Authorization: Bearer <token>
{ "title": "New Article", "status": "draft" }

# Обновить
PATCH /items/articles/42
{ "status": "published" }

# Удалить
DELETE /items/articles/42

Фильтры:

# Операторы: _eq, _neq, _lt, _lte, _gt, _gte, _in, _nin, _null, _nnull, _contains, _icontains, _starts_with, _ends_with

# Числовой диапазон
GET /items/products?filter[price][_gte]=100&filter[price][_lte]=500

# OR условие
GET /items/articles?filter[_or][0][title][_icontains]=react&filter[_or][1][content][_icontains]=react

# Связанные коллекции
GET /items/articles?filter[category][slug][_eq]=tech

# Несколько значений
GET /items/orders?filter[status][_in]=paid,shipped

Populate (deep):

# Все поля первого уровня
GET /items/articles?fields=*

# Конкретные поля связей
GET /items/articles?fields=id,title,author.name,author.email,category.name,thumbnail.id,thumbnail.filename_disk

# Вложенные связи
GET /items/articles?fields=id,title,comments.id,comments.text,comments.user.name

# Deep populate
GET /items/articles/1?deep[comments][_sort]=-date_created&deep[comments][_limit]=5

Агрегация:

# Подсчёт, сумма, среднее
GET /items/orders?aggregate[count]=*&aggregate[sum]=total&aggregate[avg]=total&filter[status][_eq]=paid

# Группировка
GET /items/orders?groupBy[]=status&aggregate[count]=*

Системные коллекции

# Пользователи
GET /users?fields=id,first_name,last_name,email,role.name

# Файлы/медиа
GET /files?fields=id,filename_disk,width,height,filesize

# Активность
GET /activity?filter[collection][_eq]=articles&sort=-timestamp&limit=20

GraphQL

# Включить в .env
GRAPHQL_SDLFILE=/tmp/graphql-schema.graphql

GraphQL доступен по /graphql:

query GetArticles($locale: String, $limit: Int) {
  articles(
    filter: { status: { _eq: "published" } }
    sort: ["-date_published"]
    limit: $limit
  ) {
    id
    title
    slug
    excerpt
    date_published
    thumbnail {
      id
      filename_disk
    }
    category {
      name
      slug
    }
    author {
      first_name
      last_name
    }
  }
}

query GetSingletonSettings {
  settings {
    site_name
    site_description
    logo { id filename_disk }
    social_links
  }
}

mutation CreateContact($data: create_contacts_input!) {
  create_contacts_item(data: $data) {
    id
    email
    message
  }
}

Realtime через WebSocket

# Подключение
ws://localhost:8055/websocket

# Аутентификация
{ "type": "auth", "access_token": "..." }

# Подписка на коллекцию
{ "type": "subscribe", "collection": "articles", "uid": "sub-1", "query": { "fields": ["id", "title"] } }

# Событие изменения
{ "type": "subscription", "event": "update", "data": [{ "id": 1, "title": "Updated" }] }

Кастомный запрос через SDK

import { createDirectus, rest, aggregate, readItems } from '@directus/sdk'

const client = createDirectus(DIRECTUS_URL).with(rest())

// Агрегация продаж за месяц
const salesStats = await client.request(
  aggregate('orders', {
    aggregate: { count: '*', sum: ['total'], avg: ['total'] },
    groupBy: ['status'],
    filter: { date_created: { _gte: '$NOW(-30 days)' } },
  })
)

// Search с весами
const results = await client.request(
  readItems('articles', {
    search: 'TypeScript',  // fulltext search по всем строковым полям
    fields: ['id', 'title', 'excerpt'],
    filter: { status: { _eq: 'published' } },
    limit: 10,
  })
)

Rate Limiting и безопасность

# Rate limiting
RATE_LIMITER_ENABLED=true
RATE_LIMITER_STORE=redis
RATE_LIMITER_POINTS=50
RATE_LIMITER_DURATION=1

# Отключить introspection GraphQL в production
GRAPHQL_INTROSPECTION=false

Сроки

Настройка GraphQL, агрегаций, Realtime подписок — 1–2 дня.