文档

包含捕获响应的 API 演练

通过来自隔离数据库的真实处理程序响应来执行健康、授权、项目创建和首选项持久性。

环境和捕获的响应

此页面上的响应是从 15 10 月 2026 的实际 Sidecar 路线中捕获的 apps/sidecar/test/helpers.ts。该工具使用迁移的内存中 SQLite 数据库、一次性文件目录、直接 AI 主机来构建应用程序处理程序，并且无需提供程序调用。请求在进程中通过 HTTP 路由器；此运行不会使用 Tauri 启动器、网络套接字、TLS 或配对的手机。

以下响应正文未经编辑。因此，标识符和时间戳属于一次性运行。您的实例返回其自己的值。使用创建请求返回的项目标识符，而不是重复使用捕获的标识符。

从存储库根启动一次性真实 HTTP 实例

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。 Sidecar 在另一次发布时选择了一个新端口。

第二个终端中的连接变量

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"

捕获的 HTTP 200

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

当地人 /health 和 /version 操作需要应用程序不记名令牌。请阅读他们的确切合同系统参考.

了解授权

在返回项目数据之前，没有承载令牌的项目请求将被拒绝。

巴什

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

捕获的 HTTP 401

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

该错误包含其标记的错误名称和可读消息。不要将消息解析为稳定的错误代码。 HTTP 状态、端点的模式及其声明的标记一起描述了失败。

使用 Authorization: Bearer … 对于已批准的申请电话。可选的 x-session-token 持票人准入后选择帐户会话。 AI桥接代币只能调用两条动作桥接路线；它们不能替代本演练中的应用程序令牌。配对网关通过其自己的路由策略接受伴随令牌。

阅读并创建项目

巴什

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

在空工作副本上捕获 HTTP 200

[]

响应是一个普通数组，没有 data 或 success 包装纸。结构有效但不完整的创建请求被业务验证拒绝：

巴什

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

捕获的 HTTP 400

{
  "_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"}'

捕获的 HTTP 201

{
  "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 在此运行中变为 false；没有选择任何组织。所有者是代理本地配置文件。分配组织需要成员资格；更新现有项目还会检查其所有者或组织角色。

读回相关数据

将创建请求返回的标识符复制到 PROJECT_ID，然后阅读详细路线：

巴什

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

捕获的 HTTP 200

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

详细信息包括所有者、可为空的组织和绘图/组件计数。创建和检索具有相关但不同的响应模式。丢失或无法访问的项目返回 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"

捕获的 HTTP 404

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

使用 PUT 保存与 JSON 兼容的值。这是一个偏好示例；它不会全局更改几何内核的单位。

巴什

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

捕获的 HTTP 200

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

读取相同的密钥将返回存储的条目，包括其更新时间戳。响应不会将值包装在项目记录或成功信封中。

捕获后续 GET、HTTP 200

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

使用 GET /api/kv?prefix=docs.walkthrough. 列出匹配的条目，或删除编码的密钥将其删除。存储拒绝其 JSON 兼容域之外的空白键、超长键和值。它不是凭证库。

处理失败和重试

结果	下一步行动
401 进行受保护的调用	验证当前启动令牌及其类型；重新启动后使用新公布的 URL。
400 关于项目创建	读取业务错误并更正请求；重新发送相同的丢失名称将再次失败。
项目或偏好的 404	检查标识符/密钥和代理帐户；应用资源的缺失/访问策略。
写入期间连接丢失	在重复写入之前读回结果资源或状态。这些创建端点不声明幂等性密钥合约。
5xx	检查 sidecar 日志和失败的服务。不要假设响应错误证明早期的持久性操作没有生效。

在生产客户端中，检查 response.ok 并解码相应的成功或错误主体。避免依赖统一的信封：本演练仅包含一个数组、普通记录和标记的故障。

下一步集成步骤

使用完整参考选择资源。这加工终点区分计算和保存刀具路径；这历史端点区分工作副本更改与提交和远程同步。这人工智能资源涵盖会话标识符和流控制。

阅读正在运行的边车 /api/openapi.json 集成不同的构建时。可下载的文档快照描述了签出的合同；它无法确定另一台机器正在运行哪个二进制文件。

所有捕获的响应一目了然

此页面上的响应是从具有新数据库的真实 sidecar 捕获的。标识符和时间戳在您的机器上会有所不同；形状和状态不会。

步	小路	地位	正文（截断）
公共卫生	`/api/health`	200	`{"status": "ok", "timestamp": "2026-10-15T02:43:50.682Z"}`
持票人失踪	`/api/projects`	401	`{"_tag": "Unauthorized", "message": "Unauthorized"}`
空项目	`/api/projects`	200	`[]`
缺少项目名称	`/api/projects`	400	`{"_tag": "BadRequest", "message": "Project name is required"}`
创建项目	`/api/projects`	201	`{"id": "ccaff34c-49f3-4a23-a6b6-427745f9641a", "name": "API walkthrough", "description": "Disposable documenta…`
阅读项目	`/api/projects/ccaff34c-49f3-4a23-a6b6-427745f9641a`	200	`{"id": "ccaff34c-49f3-4a23-a6b6-427745f9641a", "name": "API walkthrough", "description": "Disposable documenta…`
缺少偏好	`/api/kv/docs.walkthrough.units`	404	`{"_tag": "NotFound", "message": "Key not found"}`
保存首选项	`/api/kv/docs.walkthrough.units`	200	`{"key": "docs.walkthrough.units", "value": "mm", "updatedAt": "2026-10-15T02:43:50.755Z"}`
阅读偏好	`/api/kv/docs.walkthrough.units`	200	`{"key": "docs.walkthrough.units", "value": "mm", "updatedAt": "2026-10-15T02:43:50.755Z"}`

整个巡演就像一个剧本

tour.sh

#!/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 提取 id，使其没有依赖项；和 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"

删除项目会级联到其工程图、组件、刀具路径、历史记录和工作流程运行。键值条目是独立的，必须单独删除。

在 3D

游览所经历的 API 界面拖动进行轨道旋转·滚动进行缩放·右键拖动进行平移

Every API group as a column, height = operations counted from the generated OpenAPI document (270 in total). Rows are the six sidebar categories; ai (34), history (22) and costs (21) are the largest groups.