Tutorial de API con respuestas capturadas

Entorno y respuestas capturadas

Las respuestas en esta página se capturaron de las rutas reales del sidecar el 15 octubre 2026 usando apps/sidecar/test/helpers.ts. Ese arnés construye los controladores de aplicaciones con una base de datos SQLite en memoria migrada, un directorio de archivos desechable, el host de IA directo y sin llamadas a proveedores. Las solicitudes pasan por el enrutador HTTP en proceso; Esta ejecución no activa el iniciador Tauri, los enchufes de red, TLS ni un teléfono emparejado.

Los cuerpos de respuesta a continuación no están editados. Por lo tanto, los identificadores y las marcas de tiempo pertenecen a esa ejecución desechable. Su instancia devuelve sus propios valores. Utilice el identificador de proyecto devuelto por su solicitud de creación en lugar de reutilizar el identificador capturado.

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

Este token de ejemplo es sólo para un proceso de desarrollo aislado. Elija su propio valor, mantenga la terminal abierta y lea el puerto del evento listo para JSON. En un segundo terminal, configure las variables de conexión a continuación después de reemplazar READY_PORT. El sidecar elige un nuevo puerto en otro lanzamiento.

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

La base de datos de desarrollo en disco difiere de la base de datos en memoria de la captura. Si reutiliza ese directorio de datos, los proyectos y preferencias creados previamente permanecen. Utilice un directorio desechable independiente para una nueva ejecución. En su lugar, el escritorio empaquetado utiliza el directorio de datos de su aplicación nativa.

comprobar la salud

/api/health es la investigación pública. Confirma que esta ruta responde; no prueba credenciales, un proveedor de modelo ni recursos de fabricación.

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

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

el nativo /health y /version las operaciones requieren el token portador de la aplicación. Lea sus contratos exactos en el referencia del sistema.

entender la autorización

Una solicitud de proyecto sin un token al portador se rechaza antes de que se devuelvan los datos del proyecto.

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

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

El error contiene su nombre de error etiquetado y un mensaje legible. No analice el mensaje como un código de error estable. El estado HTTP, el esquema del punto final y su etiqueta declarada describen juntos el error.

Usar Authorization: Bearer … para convocatorias de solicitudes admitidas. Un opcional x-session-token selecciona una sesión de cuenta después de la admisión del portador. Los tokens de puente de IA solo pueden llamar a las dos rutas de puente de acción; no pueden sustituir un token de aplicación en este tutorial. Los tokens complementarios son aceptados por la puerta de enlace emparejada con su propia política de ruta.

Leer y crear un proyecto.

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

[]

La respuesta es una matriz simple, sin data o success envoltura. La validación empresarial rechaza una solicitud de creación estructuralmente válida pero incompleta:

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

El esquema de transporte hace name opcional, pero el controlador requiere un valor que no esté vacío. Para crear el proyecto:

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
}

El resultado de la creación es la nueva fila del proyecto. Omitido isPublic se vuelve falso en esta ejecución; no se selecciona ninguna organización. El propietario es el perfil local en funciones. Asignar una organización requiere membresía; La actualización de un proyecto existente también verifica su propietario u función de organización.

Leer datos relacionados

Copie el identificador devuelto por su solicitud de creación en PROJECT_ID, luego lea la ruta detallada:

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

Los detalles incluyen el propietario, la organización que acepta valores NULL y el recuento de dibujos/componentes. La creación y la recuperación tienen esquemas de respuesta relacionados pero diferentes. Un proyecto faltante o inaccesible devuelve 404 con Project not found or access denied; las personas que llaman no deben inferir la existencia de un proyecto privado a partir de ese resultado.

API de proyectos también actualización y eliminación de documentos. La actualización requiere un nombre que no esté vacío; la eliminación requiere el propietario o un administrador de la organización. No implemente la actualización como un parche JSON arbitrario sin seguir su contrato de carga útil.

Se aceptan listas paginadas, como configuraciones de máquinas. page (predeterminado 1) y limit (predeterminado 20, máximo 100) y devolver un pagination objeto con total y totalPages. Solicite la página siguiente en lugar de subir limit más allá de la gorra; los valores más grandes se fijan en 100.

persistir una preferencia

La API de valor clave demuestra una segunda forma de respuesta y un comportamiento de recursos faltantes. Una clave que no se ha guardado devuelve 404:

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

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

Guarde un valor compatible con JSON con PUT. Este es un ejemplo de preferencia; no cambia globalmente las unidades del núcleo de geometría.

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 lectura de la misma clave devuelve la entrada almacenada, incluida su marca de tiempo de actualización. La respuesta no incluye el valor en un registro de proyecto ni en un sobre de éxito.

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

Usar GET /api/kv?prefix=docs.walkthrough. para enumerar las entradas coincidentes, o BORRAR la clave codificada para eliminarla. La tienda rechaza claves en blanco, claves demasiado largas y valores fuera de su dominio compatible con JSON. No es una bóveda de credenciales.

Manejar fallas y reintentos

En clientes de producción, consultar response.ok y decodificar el cuerpo apropiado de éxito o error. Evite depender de un sobre uniforme: este tutorial por sí solo incluye una matriz, registros simples y fallas etiquetadas.

Próximos pasos de integración

Utilice el referencia completa para seleccionar un recurso. El puntos finales de mecanizado distinguir el cálculo de guardar una trayectoria de herramienta; el puntos finales del historial distinguir los cambios en la copia de trabajo de las confirmaciones y la sincronización remota. El recurso de IA cubre identificadores de sesión y controles de transmisión.

Lea el sidecar en marcha /api/openapi.json al integrar una construcción diferente. La instantánea de la documentación descargable describe el contrato prestado; no puede establecer qué binario está ejecutando otra máquina.

Todas las respuestas capturadas de un vistazo

Las respuestas en esta página fueron capturadas desde un sidecar real con una base de datos nueva. Los identificadores y marcas de tiempo serán diferentes en su máquina; las formas y los estados no lo harán.

Toda la gira como un solo guión.

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

El guión utiliza sed extraer la identificación para que no tenga dependencias; con jq instalado, preferir jq -r .id. Ejecútelo en un directorio de datos desechable: crea un proyecto real.

Limpiar después del recorrido.

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 eliminación del proyecto se produce en cascada en sus dibujos, componentes, rutas de herramientas, historial y ejecuciones de flujo de trabajo. La entrada clave-valor es independiente y debe eliminarse por separado.

En 3D