Présentation de l'API avec réponses capturées

Environnement et réponses capturées

Les réponses sur cette page ont été capturées à partir des itinéraires sidecar réels le 15 octobre 2026 en utilisant apps/sidecar/test/helpers.ts. Cet exploit construit les gestionnaires d'applications avec une base de données SQLite en mémoire migrée, un répertoire de fichiers jetables, l'hôte IA direct et aucun appel de fournisseur. Les requêtes transitent par le routeur HTTP en cours ; cette exécution n'utilise pas le lanceur Tauri, les prises réseau, TLS ou un téléphone couplé.

Les corps de réponse ci-dessous ne sont pas édités. Les identifiants et les horodatages appartiennent donc à cette exécution jetable. Votre instance renvoie ses propres valeurs. Utilisez l'identifiant de projet renvoyé par votre demande de création plutôt que de réutiliser l'identifiant capturé.

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

Cet exemple de jeton est uniquement destiné à un processus de développement isolé. Choisissez votre propre valeur, gardez le terminal ouvert et lisez le port à partir de l'événement JSON ready. Dans un deuxième terminal, définissez les variables de connexion ci-dessous après avoir remplacé READY_PORT. Le sidecar choisit un nouveau port lors d'un autre lancement.

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

La base de données de développement sur disque diffère de la base de données en mémoire de capture. Si vous réutilisez ce répertoire de données, les projets et préférences précédemment créés restent. Utilisez un répertoire jetable distinct pour une nouvelle exécution. Le bureau packagé utilise à la place son répertoire de données d’application natif.

Vérifier la santé

/api/health est l'enquête publique. Cela confirme que cette voie répond ; il ne teste pas les informations d'identification, un fournisseur de modèles ou des ressources de fabrication.

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

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

Le natif /health et /version les opérations nécessitent le jeton du porteur d’application. Lisez leurs contrats exacts dans le référence du système.

Comprendre l'autorisation

Une demande de projet sans jeton de porteur est rejetée avant que les données du projet ne soient renvoyées.

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

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

L'erreur contient son nom d'erreur balisé et un message lisible. N'analysez pas le message comme un code d'erreur stable. L'état HTTP, le schéma du point de terminaison et sa balise déclarée décrivent ensemble l'échec.

Utiliser Authorization: Bearer … pour les appels à candidatures admises. Un facultatif x-session-token sélectionne une session de compte après l'admission du porteur. Les jetons de pont IA ne peuvent appeler que les deux routes de pont d'action ; ils ne peuvent pas remplacer un jeton d'application dans cette procédure pas à pas. Les jetons compagnon sont acceptés par la passerelle couplée avec sa propre politique de routage.

Lire et créer un projet

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

[]

La réponse est un tableau simple, sans data ou success emballage. Une demande de création structurellement valide mais incomplète est rejetée par la validation métier :

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

Le schéma de transport fait name facultatif, mais le gestionnaire nécessite une valeur non vide. Pour créer le projet :

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
}

Le résultat de la création est la nouvelle ligne du projet. Omis isPublic devient faux dans cette exécution ; aucune organisation n'est sélectionnée. Le propriétaire est le profil local intérimaire. L'attribution d'une organisation nécessite une adhésion ; la mise à jour d'un projet existant vérifie également son rôle de propriétaire ou d'organisation.

Relisez les données associées

Copiez l'identifiant renvoyé par votre demande de création dans PROJECT_ID, puis lisez l'itinéraire détaillé :

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

Les détails incluent le propriétaire, l'organisation nullable et le nombre de dessins/composants. La création et la récupération ont des schémas de réponse liés mais différents. Un projet manquant ou inaccessible renvoie 404 avec Project not found or access denied; les appelants ne doivent pas déduire l’existence d’un projet privé à partir de ce résultat.

API de projets également la mise à jour et la suppression des documents. La mise à jour nécessite un nom non vide ; la suppression nécessite le propriétaire ou un administrateur de l'organisation. N'implémentez pas la mise à jour en tant que correctif JSON arbitraire sans suivre son contrat de charge utile.

Les listes paginées telles que les configurations de machines acceptent page (par défaut 1) et limit (par défaut 20, maximum 100) et renvoie un pagination objet avec total et totalPages. Demander la page suivante au lieu d'augmenter limit passé le plafond; les valeurs plus grandes sont limitées à 100.

Conserver une préférence

L'API clé-valeur démontre une deuxième forme de réponse et un comportement de ressource manquante. Une clé qui n'a pas été enregistrée renvoie 404 :

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

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

Enregistrez une valeur compatible JSON avec PUT. Ceci est un exemple de préférence ; cela ne change pas globalement les unités du noyau géométrique.

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 lecture de la même clé renvoie l'entrée stockée, y compris son horodatage de mise à jour. La réponse n’encapsule pas la valeur dans un enregistrement de projet ou une enveloppe de réussite.

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

Utiliser GET /api/kv?prefix=docs.walkthrough. pour répertorier les entrées correspondantes, ou SUPPRIMER la clé codée pour la supprimer. Le magasin rejette les clés vierges, les clés trop longues et les valeurs en dehors de son domaine compatible JSON. Il ne s'agit pas d'un coffre-fort d'informations d'identification.

Gérer les échecs et les tentatives

Dans les clients de production, vérifiez response.ok et décoder le corps de réussite ou d’erreur approprié. Évitez de vous fier à une enveloppe uniforme : cette procédure pas à pas comprend à elle seule un tableau, des enregistrements simples et des échecs étiquetés.

Prochaines étapes d'intégration

Utilisez le référence complète pour sélectionner une ressource. Le points finaux d'usinage distinguer le calcul de la sauvegarde d'un parcours d'outil ; le points de terminaison de l'historique distinguer les modifications de la copie de travail des validations et de la synchronisation à distance. Le Ressource IA couvre les identifiants de session et les contrôles de streaming.

Lisez le sidecar en cours d'exécution /api/openapi.json lors de l'intégration d'une version différente. L'instantané de la documentation téléchargeable décrit le contrat extrait ; il ne peut pas déterminer quel binaire une autre machine exécute.

Toutes les réponses capturées en un coup d'œil

Les réponses sur cette page ont été capturées à partir d'un véritable sidecar avec une nouvelle base de données. Les identifiants et les horodatages diffèrent sur votre machine ; les formes et les statuts ne le seront pas.

Toute la tournée comme un seul scénario

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

Le script utilise sed pour extraire l'identifiant afin qu'il n'ait aucune dépendance ; avec jq installé, préférez jq -r .id. Exécutez-le sur un répertoire de données jetable : cela crée un véritable projet.

Nettoyer après la visite

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"

La suppression du projet se répercute sur ses dessins, composants, parcours d'outils, historique et exécutions de flux de travail. L’entrée clé-valeur est indépendante et doit être supprimée séparément.

En 3D