API-Komplettlösung mit erfassten Antworten

Umgebung und erfasste Antworten

Die Antworten auf dieser Seite wurden von den tatsächlichen Sidecarrouten am 15 Oktober 2026 mit erfasst apps/sidecar/test/helpers.ts. Dieser Kabelbaum erstellt die Anwendungshandler mit einer migrierten In-Memory-SQLite-Datenbank, einem verfügbaren Dateiverzeichnis, dem direkten AI-Host und ohne Anbieteraufrufe. Die Anfragen durchlaufen den HTTP-Router in Bearbeitung; Bei diesem Lauf werden der Tauri-Launcher, Netzwerk-Sockets, TLS oder ein gekoppeltes Telefon nicht beansprucht.

Die folgenden Antworttexte sind unbearbeitet. Identifikatoren und Zeitstempel gehören daher zu diesem Wegwerflauf. Ihre Instanz gibt ihre eigenen Werte zurück. Verwenden Sie die von Ihrer Erstellungsanforderung zurückgegebene Projektkennung, anstatt die erfasste Kennung wiederzuverwenden.

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

Dieses Beispieltoken gilt nur für einen isolierten Entwicklungsprozess. Wählen Sie Ihren eigenen Wert, lassen Sie das Terminal geöffnet und lesen Sie den Port aus dem JSON-Ready-Ereignis. Legen Sie in einem zweiten Terminal nach dem Ersetzen die folgenden Verbindungsvariablen fest READY_PORT. Der Sidecar wählt bei einem weiteren Start einen neuen Port.

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

Die Entwicklungsdatenbank auf der Festplatte unterscheidet sich von der In-Memory-Datenbank des Captures. Wenn Sie dieses Datenverzeichnis wiederverwenden, bleiben zuvor erstellte Projekte und Einstellungen erhalten. Verwenden Sie für einen erneuten Durchlauf ein separates Einwegverzeichnis. Der gepackte Desktop verwendet stattdessen sein natives Anwendungsdatenverzeichnis.

Überprüfen Sie den Gesundheitszustand

/api/health ist die öffentliche Untersuchung. Es bestätigt, dass diese Route antwortet; Es werden keine Referenzen, ein Modellanbieter oder Produktionsressourcen getestet.

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

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

Der Eingeborene /health und /version für Vorgänge ist das Anwendungsträgertoken erforderlich. Lesen Sie die genauen Verträge im systemreferenz.

Autorisierung verstehen

Eine Projektanfrage ohne Bearer-Token wird abgelehnt, bevor Projektdaten zurückgegeben werden.

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

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

Der Fehler enthält seinen markierten Fehlernamen und eine lesbare Nachricht. Analysieren Sie die Nachricht nicht als stabilen Fehlercode. Der HTTP-Status, das Schema des Endpunkts und sein deklariertes Tag beschreiben zusammen den Fehler.

Verwenden Authorization: Bearer … für zugelassene Bewerbungsaufrufe. Eine optionale x-session-token wählt nach der Inhaberzulassung eine Kontositzung aus. AI-Bridge-Tokens können nur die beiden Action-Bridge-Routen aufrufen; Sie können in dieser exemplarischen Vorgehensweise kein Anwendungstoken ersetzen. Companion-Token werden vom gekoppelten Gateway mit seiner eigenen Routenrichtlinie akzeptiert.

Lesen und erstellen Sie ein Projekt

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

[]

Die Antwort ist ein einfaches Array ohne a data oder success verpackung. Eine strukturell gültige, aber unvollständige Erstellungsanforderung wird von der Geschäftsvalidierung abgelehnt:

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

Das Transportschema macht name optional, aber der Handler erfordert einen nicht leeren Wert. So erstellen Sie das Projekt:

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
}

Das Erstellungsergebnis ist die neue Projektzeile. Weggelassen isPublic wird in diesem Lauf falsch; Es ist keine Organisation ausgewählt. Der Eigentümer ist das amtierende lokale Profil. Für die Zuordnung zu einer Organisation ist eine Mitgliedschaft erforderlich; Beim Aktualisieren eines vorhandenen Projekts wird auch dessen Eigentümer- oder Organisationsrolle überprüft.

Zugehörige Daten zurücklesen

Kopieren Sie die von Ihrer Erstellungsanforderung zurückgegebene Kennung in PROJECT_ID, dann lesen Sie die detaillierte Route:

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

Zu den Details gehören der Eigentümer, die nullfähige Organisation und die Anzahl der Zeichnungen/Komponenten. Für die Erstellung und den Abruf gibt es verwandte, aber unterschiedliche Antwortschemata. Ein fehlendes oder nicht zugängliches Projekt gibt 404 mit zurück Project not found or access denied; aufrufer sollten aus diesem Ergebnis nicht auf die Existenz eines privaten Projekts schließen.

Projekt-API dokumentiert auch Aktualisierungen und Löschungen. Für die Aktualisierung ist ein nicht leerer Name erforderlich. Zum Löschen ist der Eigentümer oder ein Organisationsadministrator erforderlich. Implementieren Sie das Update nicht als willkürlichen JSON-Patch, ohne den Payload-Vertrag einzuhalten.

Seitenlisten wie Maschinenkonfigurationen akzeptieren page (standard 1) und limit (standard 20, maximal 100) und geben a zurück pagination objekt mit total und totalPages. Fordern Sie die nächste Seite an, anstatt sie zu erhöhen limit hinter der Kappe; Größere Werte werden auf 100 beschränkt.

Behalten Sie eine Präferenz bei

Die Schlüsselwert-API demonstriert eine zweite Antwortform und das Verhalten bei fehlenden Ressourcen. Ein nicht gespeicherter Schlüssel gibt 404 zurück:

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

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

Speichern Sie einen JSON-kompatiblen Wert mit PUT. Dies ist ein Präferenzbeispiel; Die Einheiten des Geometriekerns werden dadurch nicht global geändert.

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

Das Lesen desselben Schlüssels gibt den gespeicherten Eintrag einschließlich seines Aktualisierungszeitstempels zurück. Die Antwort verpackt den Wert nicht in einen Projektdatensatz oder Erfolgsumschlag.

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

Verwenden GET /api/kv?prefix=docs.walkthrough. um passende Einträge aufzulisten, oder LÖSCHEN Sie den codierten Schlüssel, um ihn zu entfernen. Der Store lehnt leere Schlüssel, überlange Schlüssel und Werte außerhalb seiner JSON-kompatiblen Domäne ab. Es handelt sich nicht um einen Tresor für Anmeldeinformationen.

Behandeln Sie Fehler und Wiederholungsversuche

Überprüfen Sie dies bei Produktionsclients response.ok und dekodieren Sie den entsprechenden Erfolgs- oder Fehlertext. Vermeiden Sie es, sich auf einen einheitlichen Umschlag zu verlassen: Diese exemplarische Vorgehensweise umfasst allein ein Array, einfache Datensätze und markierte Fehler.

Nächste Integrationsschritte

Benutzen Sie die vollständige Referenz um eine Ressource auszuwählen. Der bearbeitungsendpunkte unterscheiden Sie die Berechnung vom Speichern eines Werkzeugwegs. Die verlaufsendpunkte unterscheiden Sie Änderungen an Arbeitskopien von Commits und Remote-Synchronisierung. Der KI-Ressource deckt Sitzungskennungen und Streaming-Steuerelemente ab.

Lesen Sie die laufenden Sidecar /api/openapi.json bei der Integration eines anderen Builds. Der herunterladbare Dokumentations-Snapshot beschreibt den ausgecheckten Vertrag; Es kann nicht festgestellt werden, welche Binärdatei auf einem anderen Computer ausgeführt wird.

Alle erfassten Antworten auf einen Blick

Die Antworten auf dieser Seite wurden von einem echten Sidecar mit einer neuen Datenbank erfasst. Bezeichner und Zeitstempel unterscheiden sich auf Ihrem Computer. Formen und Status werden dies nicht tun.

Die ganze Tour als ein Drehbuch

#!/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

Das Skript verwendet sed um die ID zu extrahieren, damit sie keine Abhängigkeiten aufweist; mit jq installiert, lieber jq -r .id. Führen Sie es gegen ein verfügbares Datenverzeichnis aus: Es erstellt ein echtes Projekt.

Aufräumen nach der Tour

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"

Das Löschen des Projekts wirkt sich auf seine Zeichnungen, Komponenten, Werkzeugwege, den Verlauf und die Workflow-Ausführungen aus. Der Schlüsselwerteintrag ist unabhängig und muss separat entfernt werden.

In 3D