Procedura dettagliata API con risposte acquisite

Ambiente e risposte catturate

Le risposte in questa pagina sono state acquisite dai percorsi effettivi del sidecar il giorno 15 ottobre 2026 utilizzando apps/sidecar/test/helpers.ts. Questo cablaggio crea i gestori delle applicazioni con un database SQLite in memoria migrato, una directory di file usa e getta, l'host AI diretto e nessuna chiamata al provider. Le richieste passano attraverso il router HTTP in-process; questa corsa non esercita il launcher Tauri, le prese di rete, TLS o un telefono accoppiato.

I corpi delle risposte riportati di seguito non sono stati modificati. Identificatori e timestamp appartengono quindi a quella corsa usa e getta. La tua istanza restituisce i propri valori. Utilizza l'identificatore del progetto restituito dalla richiesta di creazione anziché riutilizzare l'identificatore acquisito.

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

Questo token di esempio è solo per un processo di sviluppo isolato. Scegli il tuo valore, mantieni il terminale aperto e leggi la porta dall'evento JSON pronto. In un secondo terminale, impostare le variabili di connessione di seguito dopo la sostituzione READY_PORT. Il sidecar sceglie una nuova porta su un altro lancio.

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

Il database di sviluppo su disco è diverso dal database in memoria dell'acquisizione. Se riutilizzi quella directory di dati, i progetti e le preferenze creati in precedenza rimangono. Utilizzare una directory usa e getta separata per una nuova corsa. Il desktop in pacchetto utilizza invece la directory dei dati dell'applicazione nativa.

Controlla la salute

/api/health è la sonda pubblica. Conferma che questo percorso risponde; non verifica le credenziali, un fornitore di modelli o le risorse di produzione.

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

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

Il nativo /health e /version le operazioni richiedono il token di connessione dell'applicazione. Leggi i loro contratti esatti nel riferimento del sistema.

Comprendere l'autorizzazione

Una richiesta di progetto senza token al portatore viene rifiutata prima che vengano restituiti i dati del progetto.

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

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

L'errore contiene il nome dell'errore contrassegnato e un messaggio leggibile. Non analizzare il messaggio come codice di errore stabile. Lo stato HTTP, lo schema dell'endpoint e il tag dichiarato insieme descrivono l'errore.

Utilizzo Authorization: Bearer … per i concorsi ammessi. Un facoltativo x-session-token seleziona una sessione del conto dopo l'ammissione al portatore. I token del ponte AI possono chiamare solo i due percorsi del ponte d'azione; non possono sostituire un token dell'applicazione in questa procedura dettagliata. I token complementari vengono accettati dal gateway associato con la propria policy di instradamento.

Leggere e creare un progetto

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

[]

La risposta è un array semplice, senza a data o success involucro. Una richiesta di creazione strutturalmente valida ma incompleta viene rifiutata dalla convalida aziendale:

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

Lo schema di trasporto fa name facoltativo, ma il gestore richiede un valore non vuoto. Per creare il progetto:

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
}

Il risultato della creazione è la nuova riga del progetto. Omesso isPublic diventa falso in questa corsa; nessuna organizzazione è selezionata. Il proprietario è il profilo locale ad interim. L'assegnazione di un'organizzazione richiede l'appartenenza; l'aggiornamento di un progetto esistente ne controlla anche il proprietario o il ruolo dell'organizzazione.

Rileggere i dati correlati

Copia l'identificatore restituito dalla tua richiesta di creazione in PROJECT_ID, quindi leggi il percorso dettagliato:

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

I dettagli includono il proprietario, l'organizzazione nullable e i conteggi di disegni/componenti. La creazione e il recupero hanno schemi di risposta correlati ma diversi. Un progetto mancante o inaccessibile restituisce 404 con Project not found or access denied; i chiamanti non dovrebbero dedurre l'esistenza di un progetto privato da tale risultato.

API dei progetti anche l'aggiornamento e la cancellazione dei documenti. L'aggiornamento richiede un nome non vuoto; l'eliminazione richiede il proprietario o un amministratore dell'organizzazione. Non implementare l'aggiornamento come patch JSON arbitraria senza seguire il contratto del payload.

Sono accettati elenchi impaginati come le configurazioni della macchina page (predefinito 1) e limit (predefinito 20, massimo 100) e restituisce a pagination oggetto con total e totalPages. Richiedi la pagina successiva invece di rilanciare limit passato il tappo; i valori più grandi sono limitati a 100.

Mantenere una preferenza

L'API chiave-valore dimostra una seconda forma di risposta e un comportamento di risorsa mancante. Una chiave che non è stata salvata restituisce 404:

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

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

Salva un valore compatibile con JSON con PUT. Questo è un esempio di preferenza; non cambia globalmente le unità del kernel della geometria.

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

La lettura della stessa chiave restituisce la voce memorizzata, incluso il timestamp di aggiornamento. La risposta non racchiude il valore in un record del progetto o in una busta di successo.

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

Utilizzo GET /api/kv?prefix=docs.walkthrough. per elencare le voci corrispondenti oppure ELIMINA la chiave codificata per rimuoverla. Lo store rifiuta chiavi vuote, chiavi troppo lunghe e valori esterni al dominio compatibile con JSON. Non è un archivio di credenziali.

Gestire gli errori e i tentativi

Nei client di produzione, controlla response.ok e decodificare il corpo appropriato del successo o dell'errore. Evitare di fare affidamento su una busta uniforme: questa procedura dettagliata include da sola un array, record semplici e errori contrassegnati.

Prossimi passaggi dell'integrazione

Usa il riferimento completo per selezionare una risorsa. IL punti finali della lavorazione distinguere il calcolo dal salvataggio di un percorso utensile; IL endpoint della cronologia distinguere le modifiche della copia di lavoro dai commit e dalla sincronizzazione remota. IL Risorsa IA copre gli identificatori di sessione e i controlli di streaming.

Leggi i sidecar funzionanti /api/openapi.json quando si integra una build diversa. L'istantanea della documentazione scaricabile descrive il contratto estratto; non è in grado di stabilire quale binario è in esecuzione su un'altra macchina.

Tutte le risposte acquisite a colpo d'occhio

Le risposte in questa pagina sono state catturate da un vero sidecar con un nuovo database. Gli identificatori e i timestamp saranno diversi sul tuo computer; le forme e gli stati no.

L'intero tour come un unico copione

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

Lo script utilizza sed per estrarre l'id in modo che non abbia dipendenze; con jq installato, preferisci jq -r .id. Eseguitelo su una directory di dati usa e getta: crea un vero progetto.

Pulisci dopo il 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"

L'eliminazione del progetto si estende ai disegni, ai componenti, ai percorsi utensile, alla cronologia e alle esecuzioni del flusso di lavoro. La voce del valore-chiave è indipendente e deve essere rimossa separatamente.

Nel 3D