GraphQL API

Этот документ был подготовлен при помощи ИИ

Текст может содержать неточности, устаревшие данные или технические ошибки. Пожалуйста, проверяйте критически важную информацию перед использованием.

Редактор в браузере работает с Architeezy по GraphQL, и тот же интерфейс доступен вашему коду: создание моделей, изменение объектов через контекст редактирования и подписка на изменения диаграммы.

Конечная точка	Назначение
/api/graphql	Запросы и мутации, отправляемые методом POST
/subscriptions	Подписки поверх WebSocket

Аутентификация работает как для REST API: сессионная cookie, если ваш код выполняется на том же хосте, иначе — токен bearer в заголовке Authorization.

Схема

Состав схемы определяют установленные на сервере нотации и типы представлений, поэтому читайте её интроспекцией с работающего сервера, а не из копии.

Большинство операций принимает editingContextId. Идентификатор контекста редактирования запрашивают у самого проекта:

query getEditingContextId($projectId: ID!) {
  viewer {
    project(projectId: $projectId) {
      currentEditingContext {
        id
      }
    }
  }
}

Запросы

Чтение начинается с viewer, спускается в контекст редактирования и запрашивает то, что нужно:

query getRepresentation($editingContextId: ID!, $representationId: ID!) {
  viewer {
    editingContext(editingContextId: $editingContextId) {
      id
      representation(representationId: $representationId) {
        id
        label
        kind
      }
    }
  }
}

Контекст редактирования также отвечает на вопросы об отдельном объекте, о представлениях, которые можно создать для объекта, и о результатах выражений, вычисленных на модели.

Мутации

Каждая мутация принимает один объект input и возвращает объединение типов данных ответа. Запросите __typename и разверните полученную ветвь. Вот так в проекте создают новую модель:

mutation createDocument($input: CreateDocumentInput!) {
  createDocument(input: $input) {
    __typename
    ... on CreateDocumentSuccessPayload {
      document {
        id
        name
        kind
      }
    }
    ... on ErrorPayload {
      messages {
        body
        level
      }
    }
  }
}

{
  "input": {
    "id": "f0ad7e1e-4b1a-4a55-9a3f-1d8ba0f4c0d1",
    "editingContextId": "019b2a78-5fa0-728a-b861-e51b5ad26984",
    "stereotypeId": "archimate",
    "name": "Ordering"
  }
}

Значение id во входных данных генерирует вызывающая сторона. stereotypeId задаёт тип создаваемой модели — archimate для модели ArchiMate.

Если проверка не прошла, приходит ErrorPayload с сообщениями, которые можно показать пользователю.

Подписки

Обновления приходят в реальном времени по транспорту GraphQL WebSocket на /subscriptions. Одна подписка отслеживает одно представление: открывайте её, когда представление появляется, и закрывайте, когда оно исчезает.

subscription diagramEvent($input: DiagramEventInput!) {
  diagramEvent(input: $input) {
    __typename
    ... on DiagramRefreshedEventPayload {
      id
      cause
      diagram {
        id
        nodes {
          id
          targetObjectId
        }
        edges {
          id
        }
      }
    }
    ... on ErrorPayload {
      messages {
        body
        level
      }
    }
  }
}

{
  "input": {
    "id": "8b7c3f26-6c22-4a2d-9b34-0d1de0c0a911",
    "editingContextId": "019b2a78-5fa0-728a-b861-e51b5ad26984",
    "diagramId": "019b2b47-2baa-7cf6-810f-592119ba5a3b"
  }
}

В каждом событии приходит вся диаграмма, поэтому имеющееся у вас состояние вы заменяете целиком, а не правите по частям. Поле cause равно refresh, когда событие вызвано изменением содержимого, и layout, когда оно вызвано пересчётом раскладки.

Поле id узла отличает его от других узлов диаграммы. targetObjectId — это идентификатор объекта предметной области, который узел изображает; именно по нему вы возвращаетесь к модели.

Параллельная работа

Мутации к одному проекту упорядочивает его контекст редактирования, поэтому отправляйте их параллельно — сервер сам выстроит очередь.