コンテンツへスキップ
CADCAMFUN
ドキュメント

ドキュメント

キャプチャされた応答を含む API のチュートリアル

分離されたデータベースからの実際のハンドラー応答を使用して、健全性、承認、プロジェクト作成、および設定の永続性を実行します。

英語から自動翻訳されています。 英語の原文を見る

環境とキャプチャされた応答

このページの回答は、15 10 月 2026 の実際のサイドカー ルートからキャプチャされたものです。 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 イベントからポートを読み取ります。 2 番目のターミナルで、置き換えた後、以下の接続変数を設定します。 READY_PORT。サイドカーは、別の起動時に新しいポートを選択します。

2 番目のターミナルの接続変数 
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 ブリッジ トークンは 2 つのアクション ブリッジ ルートのみを呼び出すことができます。このチュートリアルでは、アプリケーション トークンの代わりに使用することはできません。コンパニオン トークンは、独自のルート ポリシーを持つペアのゲートウェイによって受け入れられます。

プロジェクトを読んで作成する

バッシュ 
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
  }
}

詳細には、所有者、Null 可能な組織、図面/コンポーネントの数が含まれます。作成と取得には、関連するものの異なる応答スキーマがあります。プロジェクトが見つからないかアクセスできない場合は、404 が返されます Project not found or access denied;呼び出し元は、その結果からプライベート プロジェクトの存在を推測すべきではありません。

プロジェクトAPI ドキュメントの更新と削除も行います。更新には空ではない名前が必要です。削除には所有者または組織管理者が必要です。ペイロード規約に従わずに、任意の JSON パッチとして更新を実装しないでください。

マシン構成などのページ付きリストを受け入れます page (デフォルト 1) および limit (デフォルトは 20、最大は 100) を返します。 pagination オブジェクト total そして totalPages。上げる代わりに次のページをリクエストする limit キャップを越えたところ。より大きな値は 100 にクランプされます。

設定を維持する

Key-Value API は、2 番目の応答形状と欠落リソースの動作を示します。保存されていないキーは 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. 一致するエントリをリストするには、エンコードされたキーを DELETE して削除します。ストアは、空白キー、長すぎるキー、および JSON 互換ドメイン外の値を拒否します。これは資格情報ボールトではありません。

失敗と再試行を処理する

結果次のアクション
保護された通話の 401現在の起動トークンとそのタイプを確認します。再起動後、新しく発表された URL を使用してください。
プロジェクト作成に関する 400ビジネス エラーを読み、リクエストを修正します。同じ欠落した名前を再送信すると、再び失敗します。
プロジェクトまたは設定に関する 404識別子/キーと代理アカウントを確認してください。リソースの欠落/アクセス ポリシーを適用します。
書き込み中の接続喪失書き込みを繰り返す前に、結果のリソースまたは状態を読み戻します。これらの作成エンドポイントは、べき等キー コントラクトを宣言しません。
5xxサイドカーのログと失敗したサービスを検査します。応答エラーが、以前の永続操作が有効になっていなかったことを証明するとは考えないでください。

実稼働クライアントでは、チェックを入れます response.ok そして、適切な成功またはエラーの本文をデコードします。均一なエンベロープに依存することは避けてください。このウォークスルーには、配列、プレーン レコード、およびタグ付けされた障害だけが含まれています。

次の統合ステップ

を使用します。 完全な参照 をクリックしてリソースを選択します。の 加工エンドポイント 計算とツールパスの保存を区別します。の 履歴エンドポイント 作業コピーの変更をコミットやリモート同期から区別します。の AIリソース セッション識別子とストリーミング制御について説明します。

走行中のサイドカーを読む /api/openapi.json 異なるビルドを統合する場合。ダウンロード可能なドキュメントのスナップショットには、チェックアウトされた契約が説明されています。別のマシンがどのバイナリを実行しているかを確認することはできません。

キャプチャされたすべての応答が一目でわかる

このページの応答は、新しいデータベースを使用して実際のサイドカーからキャプチャされたものです。識別子とタイムスタンプはマシンによって異なります。形状やステータスは異なります。

ステップパス状態本体（切り詰められたもの）
公衆衛生/api/health200{"status": "ok", "timestamp": "2026-10-15T02:43:50.682Z"}
紛失したベアラー/api/projects401{"_tag": "Unauthorized", "message": "Unauthorized"}
空のプロジェクト/api/projects200[]
プロジェクト名がありません/api/projects400{"_tag": "BadRequest", "message": "Project name is required"}
プロジェクトの作成/api/projects201{"id": "ccaff34c-49f3-4a23-a6b6-427745f9641a", "name": "API walkthrough", "description": "Disposable documenta…
プロジェクトを読む/api/projects/ccaff34c-49f3-4a23-a6b6-427745f9641a200{"id": "ccaff34c-49f3-4a23-a6b6-427745f9641a", "name": "API walkthrough", "description": "Disposable documenta…
設定がありません/api/kv/docs.walkthrough.units404{"_tag": "NotFound", "message": "Key not found"}
設定の保存/api/kv/docs.walkthrough.units200{"key": "docs.walkthrough.units", "value": "mm", "updatedAt": "2026-10-15T02:43:50.755Z"}
読み取り設定/api/kv/docs.walkthrough.units200{"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.