Справочник по API

Обзор

Сайдкар представляет собой одиночный эффект HttpApi. Каждая конечная точка является типизированным HttpApiEndpoint с телами запросов и ответов с проверкой схемы, поэтому эта ссылка, сгенерированный SDK и работающий сервер происходят из одного и того же объявления в packages/api.

Базовый URL

Размещенного API CADCAMFUN не существует. Сайдкар работает на вашей машине, связывает 127.0.0.1 на порту, выбранном операционной системой (она прослушивает порт 0), проверяет свой собственный /api/healthи только затем печатает одну строку JSON на стандартный вывод. Базовый URL-адрес http://127.0.0.1:<port> из этой линии.

export CADCAMFUN_TOKEN=dev-token
CADCAMFUN_DATA_DIR=$(mktemp -d) \
CADCAMFUN_MIGRATIONS_DIR=$PWD/packages/db/drizzle \
CADCAMFUN_AI_OFFLINE=true \
  bun --no-env-file apps/sidecar/src/main.ts
# stdout: {"event":"ready","port":46709}
export CADCAMFUN_URL=http://127.0.0.1:46709

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

В контракте заявлена одна схема безопасности, bearer (HTTP Bearer). 324 из 325 операций требуют этого; только GET /api/health является общедоступным.

curl -s "$CADCAMFUN_URL/api/health"
curl -s "$CADCAMFUN_URL/api/projects" -H "Authorization: Bearer $CADCAMFUN_TOKEN"

Конвенции

• JSON на входе, JSON на выходе. Тела application/json если на карточке не указано иное: две составные загрузки, один веб-перехватчик октетного потока, загрузочный файл JavaScript, загрузка в формате zip, двоичный файл плагина и два потока событий.
• Идентификаторы операций отмечены точками. projects.get, vcs.commit: тег группы, точка, имя метода, используемое сгенерированными клиентами.
• Ошибки типизированы. Сбои объявляются для каждой конечной точки и влекут за собой _tag; включите его вместо разбора сообщений. В контракте 401 объявляется в операциях 269, 500 в 264 и 400 в 206.
• Операционные якоря стабильны. Каждая карта может быть связана как #op-<method>-<path>, например /docs/api/projects#op-get-api-projects-id.

Потоковое вещание

curl -N "$CADCAMFUN_URL/api/projects/$PROJECT_ID/events" \
  -H "Authorization: Bearer $CADCAMFUN_TOKEN"

Клиенты

@cadcamfun/api/sdk генерируется из этого же контракта: каждый идентификатор операции ниже является типизированным методом CadCam.make(...), принимая один простой ввод параметров пути и полей тела. Генерируется 259 из 325 операций; каждая карта показывает свое точное название.

import { CadCam } from "@cadcamfun/api/sdk"

const client = CadCam.make({
  baseUrl: process.env.CADCAMFUN_URL!,
  headers: { authorization: `Bearer ${process.env.CADCAMFUN_TOKEN}` },
})

const projects = await client.projects.list()
const created = await client.projects.create({ name: "Bracket" })

Ресурсы

Операции 325 в группах 35, упорядоченные по тому, что они обслуживают.

Основной

Дизайн

Производство

Ресурсы

Расширения

Счета

документ OpenAPI

Скачать /docs/api/openapi.json (зарегистрированный снимок, отображаемый на этом сайте) или получить действующий документ из работающей сайдкара по адресу /api/openapi.json. Восстановите снимок с помощью bun run generate:api-reference в packages/web после изменения конечной точки.

Контракт и сервер

@cadcamfun/api определяет схемы запросов и ответов с помощью Effect HttpApi. Он экспортирует корень Api, записи домена, ошибки с тегами и клиенты. Обработчики запросов, решения об авторизации, запросы к базе данных и вызовы провайдеров выполняются в боковой панели. Импорт схемы не запускает сервер.

Сайдкар публикует свой обслуживаемый контракт на GET /api/openapi.json. Используйте этот рабочий документ для проверки методов, параметров пути, полезных данных и кодов состояния приложения, к которому вы подключены. Сервер собирает свои группы в apps/sidecar/src/layers.ts; общий контракт собран в packages/api/src/index.ts.

Аутентификация и личность

Защищенные маршруты требуют Authorization: Bearer <token>. Рабочий стол получает новый токен приложения при запуске его вспомогательного приложения. GET /api/health является исследованием общественного здравоохранения; родной /health и /version защищены. Токены носителя приложения сравниваются с использованием безопасного по времени сравнения.

Дополнительный x-session-token осуществляет учетную сессию JWT. Токен-носитель допускает локальное приложение; сеанс выбирает свою действующую учетную запись. Отсутствующий, просроченный, недействительный или потерянный сеанс возвращается к локальному профилю установки. Затем обработчики ресурсов проверяют право собственности или доступ организации с помощью помощников авторизации репозитория.

Токен моста с ограниченной областью действия допускает только GET /api/ai/actions и POST /api/ai/actions/invoke. Он не предоставляет доступ к CRUD проекта, настройкам учетных данных или другим маршрутам HTTP. Его проект и область чтения/записи снова проверяются мостом действий.

Семейства ресурсов

• Дизайн: проекты, чертежи, компоненты, версии чертежей, импорт/экспорт объектов, точный анализ САПР, экспорт STEP и анализ сборок.
• Производство: траектории и версии инструмента, комментарии, предложения генератора, синтаксический анализ, проверка воспроизведения, собственные производственные задания, материалы, инструменты, конфигурации станков, элементы библиотеки и производственные затраты.
• Ассистент: поставщики, учетные данные, модели, сеансы, очереди потоковой передачи, элементы управления сеансами, действия, память проекта, контекст рабочей области и советы без сохранения состояния.
• Сотрудничество: ветки, коммиты, различия, запросы на включение, обзоры, зеркала GitHub, файлы и запуски рабочих процессов, события в реальном времени и сопряжение сопутствующих ресурсов.
• Сервисы приложений: пользователи, аутентификация, организации, уведомления, файлы, плагины, выставление счетов, аналитика, список ожидания, конфигурация MCP и локальное хранилище значений ключа.

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

Ответы и неудачи

Распространенные ошибки с тегами сопоставляются с HTTP 400 (BadRequest), 401 (Unauthorized), 403 (Forbidden), 404 (NotFound), 405 (MethodNotAllowed), 409 (Conflict) и 500 (InternalError). Их заявленные схемы имеют удобочитаемый для человека вид. message. Некоторые группы используют конверт с success: false, message, и errors; небольшое количество использует error поле.

Ответы об успехе могут быть записью, массивом, значением, допускающим значение NULL, или конвертом. Envelope включает в себя success, message, и data; EnvelopeOpt делает сообщение необязательным. Конечные точки создания явно объявляют 201, где это необходимо. Не делайте вывод об успехе исключительно на основе поля JSON, не проверив статус HTTP и схему конечной точки.

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

Используйте общий клиент

ApiClient.layer занимает baseUrl и приложение token. Он предоставляет транспорт выборки и промежуточное программное обеспечение для авторизации клиента. Его методы взяты непосредственно из Api, поэтому этот клиент также охватывает операции, пропущенные при генерации кода.

import { ApiClient } from "@cadcamfun/api"
import { Effect } from "effect"

const projects = Effect.gen(function* () {
  const api = yield* ApiClient
  return yield* api.projects.list()
}).pipe(Effect.provide(ApiClient.layer({ baseUrl, token })))

Базовый URL-адрес — это адрес обратной связи и назначенный порт боковой панели. Решите проблему с помощью подключения к рабочему столу, а не сохраняйте порт при каждом запуске. Не допускайте попадания токенов в URL-адреса и журналы.

Запросы на проектирование и изготовление

Использование проектных операций /api/projects; чертежи и траектории имеют свои собственные коллекции и подробные маршруты. POST /api/toolpaths/generate создает G-код, анализируемые данные программы, предупреждения и статистику на основе настроек генератора и геометрии. /suggest, /parse, и /verify предоставляйте рекомендации по параметрам, интерпретацию G-кода и воспроизведение акций. Эти вычисления не создают сохраненную траекторию инструмента.

POST /api/toolpaths/manufacture принимает версионный снимок САПР и возвращает результат ядра с ЧПУ, назначениями инструментов, данными резки, заявлениями, проблемами и уровнем выпуска. Сохраните результирующий документ отдельно с помощью операции создания или обновления траектории. Видеть Настройки для проверки доказательств во время стойкости.

POST /api/cad/exact/analyze, /step, и /assembly принять явные элементы или сохраненный идентификатор чертежа. При чтении сохраненного рисунка применяются обычные проверки доступа к рисунку вызывающего объекта.

Потоковая передача и восстановление

Поток AI переносит типизированные события для текста, рассуждений, вызовов и результатов инструментов, запросов разрешений и вопросов, повторных попыток, состояния хода, контекста и завершения. Клиенты должны получать события постепенно и сохранять идентификатор сеанса. Завершение HTTP-соединения не является достаточным свидетельством завершения поворота модели: состояние сеанса можно прочитать снова после повторного подключения.

Схемы событий ИИ живут в packages/api/src/ai-events.ts и packages/ai/src/events.ts. Общие события в реальном времени используют группу событий. Двоичные загрузки, ответы начальной загрузки плагина JavaScript и подписанные необработанные тела веб-перехватчиков требуют собственной обработки транспорта.

Список маршрутов, которые используют страницы их результатов page и limit параметры запроса. Для конфигураций машины, page по умолчанию — 1, limit по умолчанию используется 20 и ограничивается 1–100, а ответ передает pagination с page, limit, total, и totalPages (apps/sidecar/src/http/machine-configs.ts). Проверьте справочную страницу каждой группы на предмет параметров, которые она фактически объявляет.

Созданные SDK

@cadcamfun/httpapi-codegen отражает группы HttpApi в метаданных операции и созданных клиентах. Генератор API записывает Promise SDK в packages/api/src/sdk/generated и воздействовать на клиентов, чтобы packages/api/src/client/generated. Публичный Promise SDK экспортируется как @cadcamfun/api/sdk.

bun run --filter @cadcamfun/api generate
bun run --filter @cadcamfun/api generate:check

В обеих сгенерированных целях отсутствуют многочастная загрузка профиля, многокомпонентная установка плагина, создание MCP с несколькими схемами успеха, обновление MCP с конфликтующими идентификаторами, создание траектории проекта с повторяющимися входными именами и обслуживание файла плагина с заголовками потока. Цель Promise также не включает в себя необработанные веб-перехватчики Stripe, загрузку плагина JavaScript, загрузку двоичных файлов и запросы генерации/предложения генератора. Эти упущения очевидны в packages/api/scripts/generate-clients.ts; использовать контрактного клиента или соответствующий необработанный транспорт для этих операций.

Исходная организация

groups/ содержит контракты ресурсов. Общая геометрия и схемы CAM взяты из @cadcamfun/core; cad-exact.ts, cam-kernel.ts, и cam-program.ts описывать богатые результаты CAD/CAM и переносимые документы. client.ts создает контрактный клиент, а сценарий генерации владеет сгенерированными целями и списками пропусков.

Правила интеграции

Повторно используйте схемы контрактов на границах транспорта и сохраняйте зависимости базы данных во вспомогательном компоненте. Представьте конечную точку через ее контракт, обработчик, службу или репозиторий, а также сфокусированное покрытие HTTP вместе. Сгенерированные файлы являются выходными данными: отредактируйте их контракт или генератор и заново сгенерируйте их. Версия схемы API, версия переносимого файла и версия API плагина описывают отдельные контракты.

Ссылка на ресурс

325 операций через 232 пути и 35 группы ресурсов, с 56 именованными схемами. На каждой странице ресурса перечислены его операции и показаны объявленные параметры пути/запроса/заголовка, обязательные и необязательные поля, значения, допускающие значение NULL, типы контента, статусы успеха и ошибки, а также полные схемы.

Данные исходят из packages/api/src/index.ts, тот же составленный контракт HttpApi, используемый клиентами и вспомогательным устройством. На страницах описывается выданный контракт; проверить работающий сервер /api/openapi.json если вы подключитесь к другой версии.

Скачать OpenAPI JSON · Отслеживайте запросы с записанными ответами

Соглашения о подключении и запросе

API предоставляется локальным дополнительным модулем, а не фиксированной размещенной конечной точкой. Tauri получает динамически выбранный URL-адрес обратной связи и токен запуска. Запускаемая вручную сайдкар объявляет о своем порте в событии готовности JSON. Вместо этого сопряженный мобильный клиент подключается через настроенный шлюз HTTPS.

curl --silent --show-error "$CADCAMFUN_URL/api/projects" \
  --header "Authorization: Bearer $CADCAMFUN_TOKEN"

Установите обе переменные из фактического соединения. В шаблонах запросов на страницах ресурсов намеренно используются заполнители и файлы полезной нагрузки. Необязательные транспортные поля не являются обещаниями, что каждая бизнес-операция может их пропустить: например, создание проекта отклоняет отсутствующее имя в его обработчике.

Создано эталонное обслуживание

packages/web/script/generate-api-reference.mjs считывает составленный контракт, используя установленную реализацию Effect пакета API, и записывает эталонный JSON. Worker документации потребляет сгенерированный контент; он не инициализирует сервер приложений для ответа на запросы документации.

bun run generate:api-reference
bun run check:api-reference
bun run check:docs-index

Покрытие ресурсов проверяется по каждой объявленной операции. Вновь добавленная группа должна получить метаданные и навигацию, предназначенные для читателя, а измененный запрос или ответ должен быть создан заново. Рукописные руководства по-прежнему объясняют правила авторизации, побочные эффекты, конфигурацию службы и ограничения, которые не может выразить одна только схема HTTP.

Рецепты интеграции

Начните с перехваченные HTTP-запросы чтобы увидеть, как на самом деле реагируют создание проекта, бизнес-проверка, отклонение носителя, связанные записи и сохранение значений ключей. Использовать типизированная клиентская интеграция для воспроизведения этих операций с помощью Promise SDK или клиента Effect и обработки их отдельных каналов сбоев.

Эти рецепты связывают контракты HTTP с реальным поведением службы. Схема может описывать требуемое присутствие, кодировку и возвращаемую форму; связанное с ним руководство объясняет правила доступа, эффекты сохранения, поддерживаемое восстановление и ограничения, которые нельзя вывести только на основе этих типов.

Операции на группу ресурсов

В настоящее время в контракте объявлены операции 270 в группах 34, все в одном bearer Схема безопасности HTTP. Единственная операция без защиты носителя — это проверка общественного здравоохранения. Таблица вычисляется на основе сгенерированного документа OpenAPI: операций на группу, используемых методов HTTP, количества различных путей и одного репрезентативного пути.

Коды статуса по контракту

Подсчет каждого объявленного ответа один раз за операцию дает следующую картину того, что клиент должен быть готов декодировать:

Каждая ошибка является ошибкой с тегом Effect, поэтому ее тело JSON всегда содержит _tag дискриминатор рядом со своими полями. Существует три семейства кузовов, унаследованных от устаревших обработчиков, поэтому существующие клиенты продолжают работать:

{ "_tag": "NotFound", "message": "Project not found" }

{ "_tag": "EnvNotFound", "success": false, "message": "Material not found", "errors": null }

{ "_tag": "KeyedInternal", "error": "Failed to load components" }

Конверты успеха отражают конверт ошибки: { success: true, message, data }, где data может быть null. EnvelopeOpt вариант опускается message когда обработчик его не предоставил. Включить _tag а не о присутствии message или error.

Как обрабатывается запрос

1. Маршрутизатор соответствует методу и пути. Неизвестные маршруты никогда не достигают обработчика.
2. Промежуточное программное обеспечение носителя сравнивает токен за постоянное время. Отсутствующий или неправильный токен останавливает запрос с помощью 401 перед декодированием.
3. Путь, запрос, заголовки и тело декодируются по схемам операции. Структурные проблемы становятся 400 без запуска бизнес-кода.
4. Обработчик разрешает действующую учетную запись, проверяет право собственности или членство в организации (403/404) и запускает службу.
5. Результат кодируется с помощью объявленной схемы успеха или сбоя с его помеченной схемой ошибки и статусом.

Ответы, которые не являются JSON

Сгенерированный Promise SDK отклоняет потоковый ответ, тип контента которого не соответствует text/event-stream с ClientError("UnsupportedContentType")и одно событие SSE размером более 16 МиБ с SseEventTooLarge.

Вызов API без клиента

type TaggedError = { _tag: string; message?: string; error?: string }

async function call<T>(base: string, token: string, method: string, path: string, body?: unknown): Promise<T> {
  const response = await fetch(new URL(path, base), {
    method,
    headers: {
      authorization: `Bearer ${token}`,
      ...(body === undefined ? {} : { "content-type": "application/json" }),
    },
    body: body === undefined ? undefined : JSON.stringify(body),
  })
  if (response.status === 204) return undefined as T
  const payload = await response.json()
  if (!response.ok) {
    const failure = payload as TaggedError
    throw new Error(`${response.status} ${failure._tag}: ${failure.message ?? failure.error}`)
  }
  return payload as T
}

const project = await call<{ id: string; name: string }>(
  process.env.CADCAMFUN_URL!, process.env.CADCAMFUN_TOKEN!,
  "POST", "/api/projects", { name: "Bracket" },
)

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

Через 3Д