GraphQL API

This document was generated using AI assistance

Content may include inaccuracies, outdated information, or technical errors. Users are advised to cross-check critical information before implementation.

The editor in the browser works with Architeezy over GraphQL, and the same interface is open to your code: creating models, changing objects through an editing context and subscribing to changes of a diagram.

Endpoint	Purpose
/api/graphql	Queries and mutations, sent as POST
/subscriptions	Subscriptions over WebSocket

Authentication works as for the REST API: a session cookie when your code runs on the same host, otherwise a bearer token in the Authorization header.

Schema

The notations and representation kinds installed on a server determine what its schema contains, so read the schema from the running server by introspection rather than from a copy.

Most operations take an editingContextId. Read a project's editing context id from the project:

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

Queries

Reads start from viewer, descend into an editing context, and ask for what they need:

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

An editing context also answers questions about a single object, the representations that can be created on an object, and the results of expressions evaluated against the model.

Mutations

Every mutation takes one input object and returns a union of payload types. Ask for __typename and unwrap the branch you got. This is how a new model is created inside a project:

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"
  }
}

The id in the input is generated by the caller. stereotypeId names the kind of model to create - archimate for an ArchiMate model.

A validation failure comes back as ErrorPayload with messages you can show to a user.

Subscriptions

Live updates arrive over the GraphQL WebSocket transport at /subscriptions. One subscription tracks one representation: open it when the representation becomes visible, close it when it goes away.

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"
  }
}

Each event carries the whole diagram, so you replace the state you hold rather than patching it. cause is refresh when the event follows a change to the content and layout when it follows a re-layout.

A node's id identifies it inside the diagram. targetObjectId is the identifier of the domain object the node stands for, and it is the one to use when you go back to the model.

Concurrency

Mutations that target the same project are serialized by its editing context, so you may send them concurrently and the server will order them.