Пошаговое руководство по API с захваченными ответами

Окружающая среда и полученные ответы

Ответы на этой странице были получены с реальных маршрутов колясок 15 октября 2026 с помощью apps/sidecar/test/helpers.ts. Эта система создает обработчики приложений с помощью перенесенной базы данных SQLite в памяти, одноразового каталога файлов, прямого хоста AI и без вызовов провайдера. Запросы проходят через HTTP-маршрутизатор в процессе; при этом запуске не задействуются средство запуска Tauri, сетевые сокеты, TLS или сопряженный телефон.

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

CADCAMFUN_TOKEN=local-development-token \
CADCAMFUN_DATA_DIR=/tmp/cadcamfun-api-walkthrough \
CADCAMFUN_MIGRATIONS_DIR="$PWD/packages/db/drizzle" \
CADCAMFUN_AI_HOST=direct \
CADCAMFUN_AI_OFFLINE=1 \
bun --no-env-file apps/sidecar/src/main.ts

Этот пример токена предназначен только для изолированного процесса разработки. Выберите собственное значение, оставьте терминал открытым и прочтите порт из события готовности JSON. Во втором терминале установите приведенные ниже переменные подключения после замены READY_PORT. Сайдкар выбирает новый порт при следующем запуске.

export CADCAMFUN_URL="http://127.0.0.1:READY_PORT"
export CADCAMFUN_TOKEN="local-development-token"

База данных разработки на диске отличается от базы данных записи в памяти. Если вы повторно используете этот каталог данных, ранее созданные проекты и настройки останутся. Используйте отдельный одноразовый каталог для нового запуска. Вместо этого упакованный рабочий стол использует собственный каталог данных приложения.

Проверить здоровье

/api/health это общественное расследование. Это подтверждает, что этот маршрут отвечает; он не проверяет учетные данные, поставщика модели или производственные ресурсы.

curl --silent --show-error "$CADCAMFUN_URL/api/health"

{
  "status": "ok",
  "timestamp": "2026-10-15T02:43:50.682Z"
}

Родной /health и /version для операций требуется токен носителя приложения. Прочтите их точные контракты в системная ссылка.

Понимание авторизации

Запрос проекта без токена-носителя отклоняется до возврата данных проекта.

curl --silent --show-error --include "$CADCAMFUN_URL/api/projects"

{
  "_tag": "Unauthorized",
  "message": "Unauthorized"
}

Ошибка содержит помеченное имя ошибки и читаемое сообщение. Не анализируйте сообщение как стабильный код ошибки. Статус HTTP, схема конечной точки и ее объявленный тег вместе описывают сбой.

Использовать Authorization: Bearer … для допущенных вызовов приложений. Дополнительный x-session-token выбирает сеанс счета после допуска носителя. Токены моста AI могут вызывать только два маршрута моста действия; они не могут заменить токен приложения в этом пошаговом руководстве. Токены-компаньоны принимаются парным шлюзом с собственной политикой маршрутизации.

Прочтите и создайте проект

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

[]

Ответ представляет собой простой массив без data или success обертка. Структурно допустимый, но неполный запрос на создание отклоняется при бизнес-проверке:

curl --silent --show-error --request POST "$CADCAMFUN_URL/api/projects" \
  --header "Authorization: Bearer $CADCAMFUN_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{}'

{
  "_tag": "BadRequest",
  "message": "Project name is required"
}

Транспортная схема делает name необязательно, но обработчик требует непустое значение. Чтобы создать проект:

curl --silent --show-error --request POST "$CADCAMFUN_URL/api/projects" \
  --header "Authorization: Bearer $CADCAMFUN_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"name":"API walkthrough","description":"Disposable documentation example"}'

{
  "id": "ccaff34c-49f3-4a23-a6b6-427745f9641a",
  "name": "API walkthrough",
  "description": "Disposable documentation example",
  "createdAt": "2026-10-15T02:43:50.741Z",
  "updatedAt": "2026-10-15T02:43:50.741Z",
  "ownerId": "894c5064-576e-4e43-b7f0-79c6120e8345",
  "organizationId": null,
  "isPublic": false
}

Результатом создания является новая строка проекта. Опущено isPublic становится ложным в этом прогоне; ни одна организация не выбрана. Владельцем является действующий локальный профиль. Назначение организации требует членства; обновление существующего проекта также проверяет роль его владельца или организации.

Чтение связанных данных

Скопируйте идентификатор, возвращенный вашим запросом на создание, в PROJECT_ID, затем прочитайте подробный маршрут:

export PROJECT_ID="your-returned-project-id"
curl --silent --show-error "$CADCAMFUN_URL/api/projects/$PROJECT_ID" \
  --header "Authorization: Bearer $CADCAMFUN_TOKEN"

{
  "id": "ccaff34c-49f3-4a23-a6b6-427745f9641a",
  "name": "API walkthrough",
  "description": "Disposable documentation example",
  "createdAt": "2026-10-15T02:43:50.741Z",
  "updatedAt": "2026-10-15T02:43:50.741Z",
  "ownerId": "894c5064-576e-4e43-b7f0-79c6120e8345",
  "organizationId": null,
  "isPublic": false,
  "owner": {
    "id": "894c5064-576e-4e43-b7f0-79c6120e8345",
    "name": "Local user",
    "email": "local@cadcamfun.local"
  },
  "organization": null,
  "_count": {
    "drawings": 0,
    "components": 0
  }
}

Подробности включают владельца, организацию, допускающую значение NULL, а также количество чертежей/компонентов. Создание и поиск имеют связанные, но разные схемы реагирования. Отсутствующий или недоступный проект возвращает 404 с Project not found or access denied; вызывающие абоненты не должны делать вывод о существовании частного проекта на основании этого результата.

API проектов также обновление и удаление документов. Для обновления требуется непустое имя; для удаления требуется владелец или администратор организации. Не реализуйте обновление как произвольный патч JSON без соблюдения его контракта полезной нагрузки.

Постраничные списки, такие как конфигурации машины, принимаются page (по умолчанию 1) и limit (по умолчанию 20, максимум 100) и верните pagination объект с total и totalPages. Запросить следующую страницу вместо поднятия limit мимо шапки; большие значения ограничиваются 100.

Сохранять предпочтение

API «ключ-значение» демонстрирует вторую форму ответа и поведение при отсутствии ресурсов. Ключ, который не был сохранен, возвращает 404:

curl --silent --show-error "$CADCAMFUN_URL/api/kv/docs.walkthrough.units" \
  --header "Authorization: Bearer $CADCAMFUN_TOKEN"

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

Сохраните значение, совместимое с JSON, с помощью PUT. Это пример предпочтений; он не меняет глобально единицы измерения ядра геометрии.

curl --silent --show-error --request PUT "$CADCAMFUN_URL/api/kv/docs.walkthrough.units" \
  --header "Authorization: Bearer $CADCAMFUN_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"value":"mm"}'

{
  "key": "docs.walkthrough.units",
  "value": "mm",
  "updatedAt": "2026-10-15T02:43:50.755Z"
}

Чтение того же ключа возвращает сохраненную запись, включая метку времени ее обновления. Ответ не помещает значение в запись проекта или конверт успеха.

{
  "key": "docs.walkthrough.units",
  "value": "mm",
  "updatedAt": "2026-10-15T02:43:50.755Z"
}

Использовать GET /api/kv?prefix=docs.walkthrough. для получения списка совпадающих записей или УДАЛИТЬ закодированный ключ, чтобы удалить его. Хранилище отклоняет пустые ключи, слишком длинные ключи и значения за пределами своего JSON-совместимого домена. Это не хранилище учетных данных.

Обработка сбоев и повторных попыток

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

Следующие шаги интеграции

Используйте полная ссылка чтобы выбрать ресурс. конечные точки обработки отличать вычисления от сохранения траектории; тот конечные точки истории отличать изменения рабочей копии от коммитов и удаленной синхронизации. Ресурс ИИ охватывает идентификаторы сеансов и элементы управления потоковой передачей.

Прочтите бегущую сайдкар /api/openapi.json при интеграции другой сборки. Загружаемый снимок документации описывает извлеченный контракт; он не может определить, какой двоичный файл запущен на другой машине.

Все захваченные ответы с первого взгляда

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

Весь тур как один сценарий

#!/usr/bin/env bash
set -euo pipefail
: "${CADCAMFUN_URL:?set to the sidecar URL}" "${CADCAMFUN_TOKEN:?set to the launch token}"
auth=(--header "Authorization: Bearer $CADCAMFUN_TOKEN")
json=(--header "Content-Type: application/json")

curl -sS "$CADCAMFUN_URL/api/health"; echo
curl -sS -o /dev/null -w "no token -> %{http_code}\n" "$CADCAMFUN_URL/api/projects"
curl -sS "${auth[@]}" "$CADCAMFUN_URL/api/projects"; echo
curl -sS "${auth[@]}" "${json[@]}" -d '{}' "$CADCAMFUN_URL/api/projects"; echo   # 400

id=$(curl -sS "${auth[@]}" "${json[@]}" \
  -d '{"name":"API walkthrough","description":"Disposable documentation example"}' \
  "$CADCAMFUN_URL/api/projects" | sed -E 's/.*"id":"([^"]+)".*/\1/')
curl -sS "${auth[@]}" "$CADCAMFUN_URL/api/projects/$id"; echo

key=docs.walkthrough.units
curl -sS -w " %{http_code}\n" "${auth[@]}" "$CADCAMFUN_URL/api/kv/$key"   # 404 first time
curl -sS -X PUT "${auth[@]}" "${json[@]}" -d '{"value":{"units":"mm"}}' "$CADCAMFUN_URL/api/kv/$key"; echo
curl -sS "${auth[@]}" "$CADCAMFUN_URL/api/kv/$key"; echo

В скрипте используется sed извлечь идентификатор, чтобы он не имел зависимостей; с jq установлен, предпочитаю jq -r .id. Запустите его в одноразовом каталоге данных: он создаст настоящий проект.

Уборка после экскурсии

curl -sS -X DELETE --header "Authorization: Bearer $CADCAMFUN_TOKEN" "$CADCAMFUN_URL/api/projects/$id"
curl -sS -X DELETE --header "Authorization: Bearer $CADCAMFUN_TOKEN" "$CADCAMFUN_URL/api/kv/docs.walkthrough.units"

Удаление проекта каскадируется к его чертежам, компонентам, траекториям, истории и рабочим процессам. Запись значения ключа независима и должна быть удалена отдельно.

Через 3Д