API-Referenz

Überblick

Der Sidecar ist ein einzelner Effekt HttpApi. Jeder Endpunkt ist ein typisierter HttpApiEndpoint mit schemageprüften Anforderungs- und Antworttexten, daher stammen diese Referenz, das generierte SDK und der laufende Server aus derselben Deklaration in packages/api.

Basis-URL

Es gibt keine gehostete CADCAMFUN-API. Der Sidecar läuft auf Ihrer Maschine, bindet 127.0.0.1 auf einem Port, den das Betriebssystem auswählt (es lauscht auf Port 0), überprüft seinen eigenen /api/healthund gibt erst dann eine JSON-Zeile auf stdout aus. Die Basis-URL lautet http://127.0.0.1:<port> aus dieser Zeile.

export CADCAMFUN_TOKEN=dev-token
CADCAMFUN_DATA_DIR=$(mktemp -d) \
CADCAMFUN_MIGRATIONS_DIR=$PWD/packages/db/drizzle \
CADCAMFUN_AI_OFFLINE=true \
  bun --no-env-file apps/sidecar/src/main.ts
# stdout: {"event":"ready","port":46709}
export CADCAMFUN_URL=http://127.0.0.1:46709

Authentifizierung

Der Vertrag legt ein Sicherheitssystem fest, bearer (HTTP Bearer). 324 von 325 Vorgängen erfordern dies; nur GET /api/health ist öffentlich.

curl -s "$CADCAMFUN_URL/api/health"
curl -s "$CADCAMFUN_URL/api/projects" -H "Authorization: Bearer $CADCAMFUN_TOKEN"

Konventionen

• JSON rein, JSON raus. Körper sind application/json sofern auf der Karte nichts anderes angegeben ist: zwei mehrteilige Uploads, ein Oktett-Stream-Webhook, ein JavaScript-Bootstrap, ein Zip-Download, eine binäre Plugin-Datei und zwei Ereignis-Streams.
• Vorgangs-IDs sind gepunktet. projects.get, vcs.commit: das Gruppen-Tag, ein Punkt, der von den generierten Clients verwendete Methodenname.
• Fehler werden getippt. Fehler werden pro Endpunkt deklariert und tragen ein _tag; schalten Sie es ein, anstatt Nachrichten zu analysieren. Im gesamten Vertrag wird 401 für 269-Vorgänge, 500 für 264 und 400 für 206 deklariert.
• Betriebsanker sind stabil. Jede Karte ist verlinkbar als #op-<method>-<path>, zum Beispiel /docs/api/projects#op-get-api-projects-id.

Streaming

curl -N "$CADCAMFUN_URL/api/projects/$PROJECT_ID/events" \
  -H "Authorization: Bearer $CADCAMFUN_TOKEN"

Kunden

@cadcamfun/api/sdk wird aus demselben Vertrag generiert: Jede unten aufgeführte Operations-ID ist eine typisierte Methode CadCam.make(...), wobei eine flache Eingabe von Pfadparametern und Körperfeldern erfolgt. 259 der 325 Vorgänge werden generiert; Jede Karte zeigt ihren genauen Aufruf.

import { CadCam } from "@cadcamfun/api/sdk"

const client = CadCam.make({
  baseUrl: process.env.CADCAMFUN_URL!,
  headers: { authorization: `Bearer ${process.env.CADCAMFUN_TOKEN}` },
})

const projects = await client.projects.list()
const created = await client.projects.create({ name: "Bracket" })

Ressourcen

325 Vorgänge in 35 Gruppen, sortiert nach dem, was sie bedienen.

Kern

Design

Herstellung

Ressourcen

Erweiterungen

Konten

OpenAPI-Dokument

Herunterladen /docs/api/openapi.json (der eingecheckte Snapshot wird von dieser Site gerendert) oder das Live-Dokument von einem laufenden Sidecar unter abrufen /api/openapi.json. Erstellen Sie den Snapshot neu mit bun run generate:api-reference in packages/web nach dem Ändern eines Endpunkts.

Vertrag und Server

@cadcamfun/api definiert Anforderungs- und Antwortschemata mit Effect HttpApi. Es exportiert die Wurzel Api, domänendatensätze, markierte Fehler und Clients. Anforderungshandler, Autorisierungsentscheidungen, Datenbankabfragen und Anbieteraufrufe werden im Sidecar ausgeführt. Durch das Importieren eines Schemas wird kein Server gestartet.

Der Sidecar veröffentlicht seinen bedienten Vertrag unter GET /api/openapi.json. Verwenden Sie dieses laufende Dokument, um Methoden, Pfadparameter, Nutzlasten und Statuscodes für die Anwendung zu überprüfen, mit der Sie verbunden sind. Der Server stellt seine Gruppen zusammen apps/sidecar/src/layers.ts; der gemeinsame Vertrag wird in zusammengestellt packages/api/src/index.ts.

Authentifizierung und Identität

Geschützte Routen erfordern Authorization: Bearer <token>. Der Desktop erhält beim Start seines Sidecars ein neues Anwendungstoken. GET /api/health ist die Untersuchung der öffentlichen Gesundheit; einheimisch /health und /version sind geschützt. Anwendungsinhabertoken werden mit einem zeitsicheren Vergleich verglichen.

Eine optionale x-session-token trägt ein Kontositzungs-JWT. Der Inhabertoken lässt die lokale Anwendung zu; Die Sitzung wählt ihr handelndes Konto aus. Eine fehlende, abgelaufene, ungültige oder verwaiste Sitzung greift auf das lokale Profil der Installation zurück. Ressourcenhandler überprüfen dann den Besitz oder Organisationszugriff über Repository-Autorisierungshelfer.

Ein Bridge-Token mit Gültigkeitsbereich lässt nur zu GET /api/ai/actions und POST /api/ai/actions/invoke. Es gewährt keinen Zugriff auf Projekt-CRUD, Anmeldeinformationseinstellungen oder andere HTTP-Routen. Sein Projekt und Lese-/Schreibumfang werden von der Aktionsbrücke erneut überprüft.

Ressourcenfamilien

• Design: projekte, Zeichnungen, Komponenten, Zeichnungsversionen, Objektimport/-export sowie exakte CAD-Analyse, STEP-Export und Baugruppenanalyse.
• Herstellung: werkzeugwege und -versionen, Kommentare, Generatorvorschläge, Analyse, Wiedergabeüberprüfung, native Fertigungsaufträge, Materialien, Werkzeuge, Maschinenkonfigurationen, Bibliothekselemente und Produktionskosten.
• Assistent: anbieter, Anmeldeinformationen, Modelle, Sitzungen, Streaming-Runden, Sitzungssteuerungen, Aktionen, Projektspeicher, Arbeitsbereichskontext und zustandslose Ratschläge.
• Zusammenarbeit: branches, Commits, Diffs, Pull Requests, Reviews, GitHub Mirrors, Workflow-Dateien und -Läufe, Live-Events und Companion Pairing.
• Anwendungsdienstleistungen: benutzer, Authentifizierung, Organisationen, Benachrichtigungen, Dateien, Plugins, Abrechnung, Analysen, Warteliste, MCP-Konfiguration und lokaler Schlüsselwertspeicher.

Die Vertragsgruppen behalten ihre endpunktspezifischen Antwortformen. Ein Client sollte das Schema der von ihm aufgerufenen Operation dekodieren, anstatt von einem einzigen anwendungsweiten JSON-Umschlag auszugehen.

Reaktionen und Misserfolge

Häufige getaggte Fehler werden HTTP 400 zugeordnet (BadRequest), 401 (Unauthorized), 403 (Forbidden), 404 (NotFound), 405 (MethodNotAllowed), 409 (Conflict) und 500 (InternalError). Ihre deklarierten Schemata sind für Menschen lesbar message. Einige Gruppen verwenden einen Umschlag mit success: false, message, und errors; eine kleine Anzahl verwendet ein error feld.

Erfolgsantworten können ein Datensatz, ein Array, ein Nullwert zulassender Wert oder ein Umschlag sein. Envelope beinhaltet success, message, und data; EnvelopeOpt macht die Nachricht optional. Erstellungsendpunkte deklarieren gegebenenfalls explizit 201. Schließen Sie den Erfolg nicht allein aus einem JSON-Feld ab, ohne den HTTP-Status und das Endpunktschema zu überprüfen.

Durch die Schemadekodierung werden Transporteingaben validiert, bevor der Handler ausgeführt wird. Die Geschäftsvalidierung wird weiterhin im Dienst ausgeführt: Eine strukturell gültige Anfrage kann sich auf eine nicht zugängliche Zeichnung beziehen, ein veraltetes Fertigungsartefakt enthalten oder einen widersprüchlichen Zweigvorgang anfordern.

Verwenden Sie den gemeinsam genutzten Client

ApiClient.layer dauert ein baseUrl und Anwendung token. Es stellt den Abruftransport und die Client-Autorisierungs-Middleware bereit. Seine Methoden leiten sich direkt von ab Apidaher deckt dieser Client auch Vorgänge ab, die bei der Codegenerierung ausgelassen wurden.

import { ApiClient } from "@cadcamfun/api"
import { Effect } from "effect"

const projects = Effect.gen(function* () {
  const api = yield* ApiClient
  return yield* api.projects.list()
}).pipe(Effect.provide(ApiClient.layer({ baseUrl, token })))

Die Basis-URL ist die Loopback-Adresse und der zugewiesene Port des Sidecars. Lösen Sie das Problem über die Desktop-Verbindung, anstatt einen Port über mehrere Starts hinweg beizubehalten. Halten Sie Token aus URLs und Protokollen fern.

Design- und Fertigungsanfragen

Einsatz im Projektbetrieb /api/projects; zeichnungen und Werkzeugwege verfügen über eigene Sammlungen und Detailrouten. POST /api/toolpaths/generate erstellt G-Code, analysierte Programmdaten, Warnungen und Statistiken aus Generatoreinstellungen und Geometrie. /suggest, /parse, und /verify stellen Sie Parameterhinweise, G-Code-Interpretation und Bestandswiedergabe bereit. Diese Berechnungen erstellen keinen gespeicherten Werkzeugweg.

POST /api/toolpaths/manufacture akzeptiert einen versionierten CAD-Schnappschuss und gibt ein Kernel-Ergebnis mit NC, Werkzeugzuweisungen, Schnittdaten, Ansprüchen, Problemen und einem Release-Level zurück. Speichern Sie ein resultierendes Dokument separat über einen Werkzeugweg-Erstellungs- oder Aktualisierungsvorgang. Sehen Setups zur Beweisvalidierung während der Persistenz.

POST /api/cad/exact/analyze, /step, und /assembly akzeptieren Sie explizite Elemente oder eine gespeicherte Zeichnungskennung. Beim Lesen einer gespeicherten Zeichnung werden die normalen Zeichnungszugriffsprüfungen des Aufrufers angewendet.

Streaming und Wiederherstellung

Der KI-Stream überträgt typisierte Ereignisse für Text, Begründung, Toolaufrufe und -ergebnisse, Erlaubnis- und Frageanfragen, Wiederholungsversuche, Turn-Status, Kontext und Abschluss. Clients müssen Ereignisse inkrementell konsumieren und die Sitzungskennung beibehalten. Das Beenden einer HTTP-Verbindung ist kein ausreichender Beweis dafür, dass ein Modellwechsel abgeschlossen ist: Der Sitzungsstatus kann nach dem erneuten Herstellen der Verbindung erneut gelesen werden.

KI-Ereignisschemata leben in packages/api/src/ai-events.ts und packages/ai/src/events.ts. Allgemeine Live-Ereignisse verwenden die Ereignisgruppe. Binäre Downloads, JavaScript-Plugin-Bootstrap-Antworten und signierte Roh-Webhook-Körper erfordern eine eigene Transportabwicklung.

Listen Sie die Routen auf, die die Seite ihrer Ergebnisse verwendet page und limit abfrageparameter. Für Maschinenkonfigurationen page der Standardwert ist 1, limit der Standardwert ist 20 und wird auf 1–100 begrenzt, und die Antwort wird übertragen pagination mit page, limit, total, und totalPages (apps/sidecar/src/http/machine-configs.ts). Überprüfen Sie die Referenzseite jeder Gruppe auf die tatsächlich deklarierten Parameter.

Generierte SDKs

@cadcamfun/httpapi-codegen spiegelt HttpApi-Gruppen in Vorgangsmetadaten und generierte Clients wider. Der API-Generator schreibt ein Promise SDK darauf packages/api/src/sdk/generated und Effektkunden an packages/api/src/client/generated. Das öffentliche Promise SDK wird exportiert als @cadcamfun/api/sdk.

bun run --filter @cadcamfun/api generate
bun run --filter @cadcamfun/api generate:check

Both generated targets omit profile multipart upload, plugin multipart installation, MCP creation with multiple success schemas, MCP update with colliding identifiers, project toolpath creation with duplicate input names, and plugin file serving with stream headers. The Promise target also omits Stripe raw webhooks, plugin JavaScript bootstrap, binary file download, and the generator's generate/suggest requests. Diese Auslassungen sind explizit in packages/api/scripts/generate-clients.ts; verwenden Sie für diese Vorgänge den Vertragskunden oder den entsprechenden Rohtransport.

Quellorganisation

groups/ enthält Ressourcenverträge. Gemeinsam genutzte Geometrie und CAM-Schemata stammen von @cadcamfun/core; cad-exact.ts, cam-kernel.ts, und cam-program.ts beschreiben umfangreiche CAD/CAM-Ergebnisse und tragbare Dokumente. client.ts erstellt den Vertragsmandanten, während das Generierungsskript generierte Ziele und Auslassungslisten besitzt.

Integrationsregeln

Verwenden Sie Vertragsschemata an Transportgrenzen wieder und behalten Sie Datenbankabhängigkeiten im Sidecar bei. Führen Sie einen Endpunkt über seinen Vertrag, seinen Handler, seinen Dienst oder sein Repository ein und konzentrieren Sie sich gemeinsam auf die HTTP-Abdeckung. Generierte Dateien sind Ausgaben: Bearbeiten Sie ihren Vertrag oder Generator und generieren Sie sie neu. Eine API-Schemaversion, eine Portable-File-Version und eine Plugin-API-Version beschreiben separate Verträge.

Ressourcenreferenz

325 Vorgänge über 232 Pfade und 35 Ressourcengruppen, mit 56 benannten Schemas. Jede Ressourcenseite listet ihre Vorgänge auf und zeigt deklarierte Pfad-/Abfrage-/Header-Parameter, erforderliche und optionale Felder, Nullable-Werte, Inhaltstypen, Erfolgs- und Fehlerstatus sowie vollständige Schemata an.

Die Daten werden von ausgegeben packages/api/src/index.ts, derselbe zusammengesetzte HttpApi-Vertrag, der von den Clients und dem Sidecar verwendet wird. Die Seiten beschreiben den ausgecheckten Vertrag; Überprüfen Sie die laufenden Server /api/openapi.json wenn Sie eine Verbindung zu einer anderen Version herstellen.

Laden Sie OpenAPI JSON herunter · Verfolgen Sie Anfragen mit erfassten Antworten

Verbindungs- und Anforderungskonventionen

Die API wird vom lokalen Sidecar und nicht von einem fest gehosteten Endpunkt bereitgestellt. Tauri erhält seine dynamisch ausgewählte Loopback-URL und sein Starttoken. Ein manuell gestarteter Sidecar gibt seinen Port in einem JSON-Ready-Ereignis bekannt. Ein gekoppelter mobiler Client stellt stattdessen eine Verbindung über sein konfiguriertes HTTPS-Gateway her.

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

Legen Sie beide Variablen aus der tatsächlichen Verbindung fest. Anforderungsvorlagen auf Ressourcenseiten verwenden bewusst Platzhalter und Payload-Dateien. Optionale Transportfelder sind kein Versprechen, dass jeder Geschäftsvorgang sie weglassen kann: Die Projekterstellung lehnt beispielsweise einen fehlenden Namen in ihrem Handler ab.

Generierte Referenzpflege

packages/web/script/generate-api-reference.mjs liest den verfassten Vertrag mithilfe der installierten Effect-Implementierung des API-Pakets und schreibt den Referenz-JSON. Der Dokumentationsarbeiter konsumiert den generierten Inhalt; Der Anwendungsserver wird nicht für die Beantwortung von Dokumentationsanfragen initialisiert.

bun run generate:api-reference
bun run check:api-reference
bun run check:docs-index

Die Ressourcenabdeckung wird anhand jedes deklarierten Vorgangs überprüft. Eine neu hinzugefügte Gruppe muss leserorientierte Metadaten und Navigation erhalten und eine geänderte Anfrage oder Antwort muss neu generiert werden. Handschriftliche Leitfäden erläutern immer noch Autorisierungsregeln, Nebenwirkungen, Dienstkonfiguration und Einschränkungen, die ein HTTP-Schema allein nicht ausdrücken kann.

Integrationsrezepte

Beginnen Sie mit erfasste HTTP-Anfragen um zu sehen, wie Projekterstellung, Geschäftsvalidierung, Trägerablehnung, zugehörige Datensätze und Schlüsselwertpersistenz tatsächlich reagieren. Verwenden typisierte Client-Integration um diese Vorgänge mit dem Promise SDK oder dem Effect-Client zu reproduzieren und ihre unterschiedlichen Fehlerkanäle zu verwalten.

Diese Rezepte verbinden HTTP-Verträge mit dem tatsächlichen Dienstverhalten. Ein Schema kann die erforderliche Präsenz, Kodierung und eine zurückgegebene Form beschreiben; Der verlinkte Leitfaden erklärt Zugriffsregeln, Persistenzeffekte, unterstützte Wiederherstellung und Einschränkungen, die sich nicht allein aus diesen Typen ableiten lassen.

Vorgänge pro Ressourcengruppe

Der Vertrag deklariert derzeit 270 Vorgänge in 34 Gruppen, alle unter einer einzigen bearer HTTP-Sicherheitsschema. Die einzige Operation ohne Trägersicherheit ist die Untersuchung der öffentlichen Gesundheit. Die Tabelle wird aus dem generierten OpenAPI-Dokument berechnet: Operationen pro Gruppe, die verwendeten HTTP-Methoden, wie viele verschiedene Pfade und ein repräsentativer Pfad.

Statuscodes im gesamten Vertrag

Zählt man jede deklarierte Antwort einmal pro Vorgang, erhält man folgendes Bild davon, was ein Client zum Dekodieren bereit sein muss:

Jeder Fehler ist ein mit Effect markierter Fehler, daher enthält sein JSON-Körper immer a _tag diskriminator neben seinen Feldern. Es gibt drei Körperfamilien, die von den alten Handlern übernommen wurden, sodass bestehende Clients weiterhin funktionieren:

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

{ "_tag": "EnvNotFound", "success": false, "message": "Material not found", "errors": null }

{ "_tag": "KeyedInternal", "error": "Failed to load components" }

Erfolgsumschläge spiegeln den Fehlerumschlag wider: { success: true, message, data }, wo data vielleicht null. Der EnvelopeOpt variante weggelassen message wenn der Hundeführer keines zur Verfügung gestellt hat. Einschalten _tag und nicht auf der Anwesenheit von message oder error.

Wie eine Anfrage bearbeitet wird

1. Der Router gleicht Methode und Pfad ab. Unbekannte Routen erreichen nie einen Handler.
2. Die Träger-Middleware vergleicht den Token in konstanter Zeit. Ein fehlendes oder falsches Token stoppt die Anfrage mit 401 vor der Dekodierung.
3. Pfad, Abfrage, Header und Text werden anhand der Schemata des Vorgangs dekodiert. Strukturelle Probleme werden zu 400, ohne dass Geschäftscode ausgeführt wird.
4. Der Handler löst das handelnde Konto auf, prüft den Besitz oder die Organisationsmitgliedschaft (403/404) und führt den Dienst aus.
5. Das Ergebnis wird mit dem deklarierten Erfolgsschema oder der Fehler mit seinem getaggten Fehlerschema und Status codiert.

Antworten, die nicht JSON sind

Das generierte Promise SDK lehnt eine Streaming-Antwort ab, deren Inhaltstyp es nicht ist text/event-stream mit ClientError("UnsupportedContentType")und ein einzelnes SSE-Ereignis größer als 16 MiB mit SseEventTooLarge.

Aufruf der API ohne Client

type TaggedError = { _tag: string; message?: string; error?: string }

async function call<T>(base: string, token: string, method: string, path: string, body?: unknown): Promise<T> {
  const response = await fetch(new URL(path, base), {
    method,
    headers: {
      authorization: `Bearer ${token}`,
      ...(body === undefined ? {} : { "content-type": "application/json" }),
    },
    body: body === undefined ? undefined : JSON.stringify(body),
  })
  if (response.status === 204) return undefined as T
  const payload = await response.json()
  if (!response.ok) {
    const failure = payload as TaggedError
    throw new Error(`${response.status} ${failure._tag}: ${failure.message ?? failure.error}`)
  }
  return payload as T
}

const project = await call<{ id: string; name: string }>(
  process.env.CADCAMFUN_URL!, process.env.CADCAMFUN_TOKEN!,
  "POST", "/api/projects", { name: "Bracket" },
)

Bevorzugen Sie die generierten Clients in TypeScript: Sie kennen den Erfolgsstatus und die deklarierten Fehlerstatus jeder Operation und behandeln alles andere als UnexpectedStatus statt zu raten.

In 3D