REST API

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

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

Architeezy предоставляет REST API по пути /api на том же хосте, что и само приложение. Он охватывает пространства моделирования, проекты, модели, представления, участников проектов и пользователей, а также отдаёт содержимое моделей во всех форматах, которые сервер может записать.

Сгенерированное описание OpenAPI доступно по адресу /v3/api-docs, а интерактивный обозреватель к нему — по адресу /swagger-ui/index.html.

Аутентификация

Запросы на чтение работают без учётных данных и возвращают общедоступные сущности. Всё остальное — создание, изменение, удаление и чтение сущностей с более высоким уровнем конфиденциальности — доступно только после входа в систему. Войти можно двумя способами.

Приложение, которое отдаётся с того же хоста, что и Architeezy, наследует сессию браузера. Чтобы отправить cookie, добавьте к запросам credentials: "include":

const response = await fetch('/api/users/current', { credentials: 'include' });
const user = response.status === 204 ? null : await response.json();

На запрос GET /api/users/current анонимный клиент получает 204 No Content, а вошедший — 200 со своим профилем. Так приложение при запуске узнаёт, вошёл ли пользователь.

Токен Bearer

Инструменты, работающие вне браузера, — скрипт, настольное приложение, задача CI — входят по токену доступа OpenID Connect, который отправляют в заголовке:

GET /api/models HTTP/1.1
Host: architeezy.com
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAi...

Для этого предназначен публичный клиент architeezy-api. Он поддерживает поток authorization code с петлевыми (loopback) URI перенаправления (http://localhost:* и http://127.0.0.1:*). Локальный инструмент открывает системный браузер, ловит перенаправление на порту, который сам слушает, и меняет код на токены.

Запросите вместе с openid также scope offline_access — и вы получите автономный токен обновления. Он действует и после завершения сессии браузера, поэтому фоновая задача может выпускать новые токены доступа без участия человека. Храните его как пароль.

Конечные точки и идентификатор клиента опубликованы, поэтому клиент может запросить их у сервера, а не хранить в коде:

$ curl https://architeezy.com/api/settings
{"aboutUrl":"https://about.architeezy.com",
 "documentationUrl":"https://docs.architeezy.com",
 "applicationsUrl":"https://apps.architeezy.com",
 "oauth2IssuerUrl":"https://auth.architeezy.com/realms/architeezy",
 "oauth2ApiClientId":"architeezy-api"}

По URL издателя доступен стандартный документ обнаружения OpenID Connect — /.well-known/openid-configuration; в нём указаны конечные точки авторизации и выдачи токенов.

Ресурсы

Путь	Ресурс
`/api/scopes`	Пространства моделирования — контейнеры верхнего уровня для проектов
`/api/projects`	Проекты, их импорты и их участники
`/api/models`	Модели, их метаданные и их содержимое
`/api/representations`	Диаграммы, таблицы, формы и документы
`/api/project-images`	Изображения, хранящиеся в проекте
`/api/project-users`	Участие в проекте
`/api/project-enrollments`	Заявки на вступление в проект и их одобрение
`/api/users`	Профили пользователей и текущий пользователь

Сущности адресуются по своему UUID, например GET /api/models/019b151f-aa97-77b2-9a08-c676443c4a00. Проекты, модели и представления можно адресовать также по цепочке slug-ов — той самой, что видна в адресной строке браузера:

Шаблон	Соответствует
`/api/projects/{scope}/{project}/{version}`	Проект
`/api/models/{scope}/{project}/{version}/{model}`	Модель
`/api/representations/{scope}/{project}/{version}/{model}`	Её представление по умолчанию
`/api/representations/{scope}/{project}/{version}/{model}/{repr}`	Представление по slug

Ответы в формате HAL

Коллекции и отдельные сущности возвращаются в формате HAL+JSON: поля сущности плюс словарь _links, а для коллекций — словарь _embedded с ключом по имени ресурса.

curl 'https://architeezy.com/api/models?size=2&sort=name,asc'

{
  "_embedded": {
    "models": [
      {
        "_links": {
          "self": {
            "href": "https://architeezy.com/api/models/019b151f-aa97-77b2-9a08-c676443c4a00"
          },
          "content": [
            {
              "href": "https://architeezy.com/api/models/demo/eip-system-design/dev/airline-ticket-aggregator/content?format=json{&inline}",
              "templated": true,
              "title": "JSON",
              "type": "application/json"
            }
          ]
        },
        "id": "019b151f-aa97-77b2-9a08-c676443c4a00",
        "scope": { "id": "019a8255-...", "slug": "demo", "name": "Demo" },
        "project": {
          "id": "019b12f8-...",
          "slug": "eip-system-design",
          "version": "dev",
          "name": "EIP System Design"
        },
        "slug": "airline-ticket-aggregator",
        "name": "Airline Ticket Aggregator",
        "confidentiality": 0,
        "contentType": "https://architeezy.com/metamodel/eip/dev/eip#EnterpriseIntegrationModel",
        "defaultRepresentation": {
          "id": "019b151f-ac0b-7a0e-aab7-78040deac6db",
          "slug": "enterpriseintegrationmodel-diagram",
          "name": "EnterpriseIntegrationModel Diagram"
        },
        "creator": { "id": "27ebbd12-...", "name": "denis" },
        "creationDateTime": "2025-12-13T00:32:33.974480Z",
        "lastModificationDateTime": "2025-12-13T01:27:55.940772Z"
      }
    ]
  },
  "_links": {
    "first": {
      "href": "https://architeezy.com/api/models?page=0&size=2&sort=name,asc"
    },
    "self": {
      "href": "https://architeezy.com/api/models?page=0&size=2&sort=name,asc"
    },
    "next": {
      "href": "https://architeezy.com/api/models?page=1&size=2&sort=name,asc"
    },
    "last": {
      "href": "https://architeezy.com/api/models?page=19&size=2&sort=name,asc"
    }
  },
  "page": { "number": 0, "size": 2, "totalElements": 39, "totalPages": 20 }
}

У каждой модели есть по одной ссылке content на каждый выходной формат, который сервер может для неё сформировать. Ссылки представляют собой шаблоны URI: перед запросом уберите часть {&inline} или подставьте в неё значение.

Постраничная выдача

Списки принимают page (нумерация с нуля) и size и отвечают блоком page с полями number, size, totalElements и totalPages. Вместо того чтобы вычислять номера страниц, идите по _links.next, пока ссылка не исчезнет:

async function fetchAllModels() {
  const models = [];
  let url = 'https://architeezy.com/api/models?size=100';
  while (url) {
    const response = await fetch(url, { credentials: 'include' });
    const page = await response.json();
    models.push(...(page._embedded?.models ?? []));
    url = page._links?.next?.href ?? null;
  }
  return models;
}

Сортировка

sort=<поле>,<направление> упорядочивает результат, например sort=name,asc или sort=lastModificationDateTime,desc. Повторите параметр, чтобы отсортировать по нескольким полям по порядку.

Фильтрация

Любой другой параметр запроса Architeezy понимает как фильтр по полю ресурса. Для моделей доступны поля id, slug, name, description, confidentiality, contentType, creationDateTime, lastModificationDateTime, а также составные формы project.slug, project.version, project.name, scope.slug, scope.name, creator.name и lastModifier.name.

Оператор задаётся в самом значении:

Значение	Смысл
`name=Order`	Равно `Order`
`name=!Order`	Не равно `Order`
`name=Order*`	Начинается с `Order`, без учёта регистра
`name=Order`	Содержит `Order`, без учёта регистра
`name=!Order`	Не содержит `Order`
`confidentiality=>=2`	Больше или равно `2`, также `>`, `<`, `<=`
`description=`	Пусто или отсутствует
`description=!`	Присутствует

Повторите параметр — условия объединятся по И. Для нетекстовых полей запятая внутри одного значения объединяет условия по ИЛИ, так что confidentiality=0,1 подходит любому из двух значений. В текстовом значении запятая читается буквально. Исключение — поля даты и времени: их части, разделённые запятыми, объединяются по И и так задают диапазон.

Перечислите в ключе несколько полей — одно условие применится ко всем сразу и сработает, если ему удовлетворяет хотя бы одно:

curl 'https://architeezy.com/api/models?name,description=*payment*&size=20'

Неизвестное поле приводит к ошибке, а не игнорируется:

{
  "detail": "Invalid filter parameters",
  "instance": "/api/models",
  "status": 400,
  "title": "Bad Request",
  "errors": [{ "message": "Unknown filter field: nope", "field": "nope" }]
}

Содержимое модели

Метаданные и содержимое — разные ресурсы. GET /api/models/{id} возвращает метаданные; GET /api/models/{id}/content возвращает сериализованную модель; та же конечная точка доступна и по цепочке slug-ов:

curl 'https://architeezy.com/api/models/demo/eip-system-design/dev/airline-ticket-aggregator/content?format=json'

{
  "json": { "version": "1.0", "encoding": "utf-8" },
  "ns": { "eip": "https://architeezy.com/metamodel/eip/dev/eip" },
  "content": [
    {
      "id": "961dae55-b6f7-53bd-8d80-cd9f70320f93",
      "eClass": "eip:EnterpriseIntegrationModel",
      "data": {
        "name": "Airline Ticket Aggregator",
        "entities": [
          {
            "id": "350261b6-fad7-52d8-a8a8-80cb9206e661",
            "eClass": "eip:Endpoint",
            "data": { "name": "API Gateway" }
          }
        ]
      }
    }
  ]
}

Формат берётся из ?format= или из заголовка Accept. Добавьте ?inline=true, чтобы браузер показал ответ, а не скачал его.

`format`	Тип содержимого	Содержимое
`json`	`application/json`	Модель в формате JSON
`xmi`	`application/vnd.xmi+xml`	Модель в формате XMI
`ttl`	`text/turtle`	Модель в формате RDF Turtle
`trig`	`application/trig`	Модель в формате RDF TriG
`archimate`	`application/xml`	Модель ArchiMate в собственном формате файлов Archi
`ifc`	`application/x-step`	Модель IFC в виде файла STEP

Любую модель можно записать как json, xmi, ttl и trig. Форматы, привязанные к нотации, предлагаются только подходящим моделям: archimate — модели ArchiMate, ifc — модели IFC. Если сервер не может сформировать запрошенный формат для этой модели, он отвечает 406 Not Acceptable.

Ещё две конечные точки отвечают на вопросы о модели, а не отдают файл. GET /api/models/{id}/owl возвращает онтологию OWL, выведенную из модели, а POST /api/projects/{id}/sparql выполняет SPARQL-запрос по проекту.

Запись содержимого

PUT /api/models/{id}/content?format=archimate заменяет содержимое модели телом запроса как есть. Чтобы создать модель и наполнить её одним вызовом, отправьте multipart/form-data на /api/models с JSON-частью с именем entity и файлом в части с именем content:

$ curl -X POST https://architeezy.com/api/models \
    -H "Authorization: Bearer $TOKEN" \
    -F 'entity={"projectId":"019b12f8-f501-7553-9f35-4cde33edea0c",
                "name":"Ordering"};type=application/json' \
    -F 'content=@ordering.archimate'

Формат загрузки Architeezy определяет по расширению файла — если вы не задали contentFormat в части entity. Формат, который не читает ни один десериализатор, получает ответ 415 Unsupported Media Type.

Коды состояния

200 при чтении или изменении, 201 при создании, 204 при удалении. 400 означает некорректный запрос или неуспешную проверку, 409 — конфликт, к примеру уже занятый slug, 415 — неподдерживаемый формат загрузки, 406 — недоступный выходной формат.

401 приходит, когда запись попытался выполнить анонимный клиент, 403 — когда вы видите сущность, но не можете её изменять. 404 покрывает и несуществующую сущность, и ту, которую вам не разрешено видеть, поэтому перебором идентификаторов не узнать, что есть на сервере.

Ошибки приходят в формате application/problem+json. В ответе 400 или 409 есть массив errors с проблемными полями, а в ответе 500 — errorId, который можно сообщить тому, кто администрирует сервер.

Аутентификация​

Сессионная cookie​

Токен Bearer​

Ресурсы​

Ответы в формате HAL​

Постраничная выдача​

Сортировка​

Фильтрация​

Содержимое модели​

Запись содержимого​

Коды состояния​