कैप्चर की गई प्रतिक्रियाओं के साथ एपीआई वॉकथ्रू

पर्यावरण और कैप्चर की गई प्रतिक्रियाएँ

इस पृष्ठ पर प्रतिक्रियाएँ 15 अक्टूबर 2026 को वास्तविक साइडकार मार्गों से ली गई थीं। apps/sidecar/test/helpers.ts. वह हार्नेस एक माइग्रेटेड इन-मेमोरी SQLite डेटाबेस, एक डिस्पोजेबल फ़ाइल निर्देशिका, प्रत्यक्ष AI होस्ट और कोई प्रदाता कॉल के साथ एप्लिकेशन हैंडलर बनाता है। अनुरोध प्रक्रिया के दौरान HTTP राउटर से गुजरते हैं; यह रन टॉरी लॉन्चर, नेटवर्क सॉकेट, टीएलएस या युग्मित फोन का उपयोग नहीं करता है।

नीचे दिए गए प्रतिक्रिया निकाय असंपादित हैं। इसलिए पहचानकर्ता और टाइमस्टैम्प उस डिस्पोजेबल रन से संबंधित हैं। आपका उदाहरण अपने स्वयं के मान लौटाता है। कैप्चर किए गए पहचानकर्ता का पुन: उपयोग करने के बजाय आपके निर्माण अनुरोध द्वारा लौटाए गए प्रोजेक्ट पहचानकर्ता का उपयोग करें।

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

यह उदाहरण टोकन केवल एक पृथक विकास प्रक्रिया के लिए है। अपना स्वयं का मान चुनें, टर्मिनल खुला रखें, और JSON तैयार इवेंट से पोर्ट पढ़ें। दूसरे टर्मिनल में, बदलने के बाद कनेक्शन वेरिएबल को नीचे सेट करें READY_PORT. साइडकार दूसरे लॉन्च पर एक नया पोर्ट चुनता है।

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

ऑन-डिस्क डेवलपमेंट डेटाबेस कैप्चर के इन-मेमोरी डेटाबेस से भिन्न होता है। यदि आप उस डेटा निर्देशिका का पुन: उपयोग करते हैं, तो पहले से बनाए गए प्रोजेक्ट और प्राथमिकताएँ बनी रहती हैं। नए सिरे से चलाने के लिए एक अलग डिस्पोजेबल निर्देशिका का उपयोग करें। पैकेज्ड डेस्कटॉप इसके बजाय अपनी मूल एप्लिकेशन डेटा निर्देशिका का उपयोग करता है।

स्वास्थ्य की जाँच करें

/api/health सार्वजनिक जांच है. यह पुष्टि करता है कि यह मार्ग उत्तर देता है; यह साख, मॉडल प्रदाता या विनिर्माण संसाधनों का परीक्षण नहीं करता है।

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

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

देसी /health और /version संचालन के लिए एप्लिकेशन बियरर टोकन की आवश्यकता होती है। में उनके सटीक अनुबंध पढ़ें सिस्टम संदर्भ.

प्राधिकरण को समझें

बिना बियरर टोकन वाले प्रोजेक्ट अनुरोध को प्रोजेक्ट डेटा लौटाने से पहले अस्वीकार कर दिया जाता है।

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

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

त्रुटि में इसका टैग किया गया त्रुटि नाम और एक पढ़ने योग्य संदेश शामिल है। संदेश को स्थिर त्रुटि कोड के रूप में पार्स न करें। HTTP स्थिति, समापन बिंदु की स्कीमा और इसका घोषित टैग मिलकर विफलता का वर्णन करते हैं।

उपयोग Authorization: Bearer … स्वीकृत आवेदन कॉल के लिए। एक वैकल्पिक x-session-token वाहक प्रवेश के बाद एक खाता सत्र का चयन करता है। एआई ब्रिज टोकन केवल दो एक्शन ब्रिज मार्गों को कॉल कर सकते हैं; वे इस वॉकथ्रू में एप्लिकेशन टोकन का स्थानापन्न नहीं कर सकते। सहयोगी टोकन युग्मित गेटवे द्वारा अपनी रूट नीति के साथ स्वीकार किए जाते हैं।

पढ़ें और एक प्रोजेक्ट बनाएं

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

[]

प्रतिक्रिया एक सादा सरणी है, बिना a के data या success रैपर. संरचनात्मक रूप से वैध लेकिन अपूर्ण निर्माण अनुरोध को व्यवसाय सत्यापन द्वारा अस्वीकार कर दिया जाता है:

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

परिवहन स्कीम बनाता है name वैकल्पिक, लेकिन हैंडलर को एक गैर-रिक्त मान की आवश्यकता होती है। प्रोजेक्ट बनाने के लिए:

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
}

निर्माण परिणाम नई परियोजना पंक्ति है। लोप isPublic इस दौड़ में झूठा हो जाता है; किसी संगठन का चयन नहीं किया गया है. स्वामी कार्यकारी स्थानीय प्रोफ़ाइल है. किसी संगठन को नियुक्त करने के लिए सदस्यता की आवश्यकता होती है; किसी मौजूदा प्रोजेक्ट को अपडेट करने से उसके मालिक या संगठन की भूमिका की भी जाँच होती है।

संबंधित डेटा वापस पढ़ें

आपके निर्माण अनुरोध द्वारा लौटाए गए पहचानकर्ता को कॉपी करें PROJECT_ID, फिर विस्तृत मार्ग पढ़ें:

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

विवरण में स्वामी, अशक्त संगठन और ड्राइंग/घटक गणना शामिल हैं। निर्माण और पुनर्प्राप्ति में संबंधित लेकिन अलग-अलग प्रतिक्रिया स्कीमा हैं। एक गुम या अप्राप्य प्रोजेक्ट 404 के साथ वापस आता है Project not found or access denied; कॉल करने वालों को उस परिणाम से किसी निजी परियोजना के अस्तित्व का अनुमान नहीं लगाना चाहिए।

प्रोजेक्ट एपीआई दस्तावेज़ अद्यतन और विलोपन भी। अद्यतन करने के लिए एक गैर-रिक्त नाम की आवश्यकता होती है; हटाने के लिए स्वामी या संगठन प्रशासक की आवश्यकता होती है। पेलोड अनुबंध का पालन किए बिना अपडेट को मनमाने JSON पैच के रूप में लागू न करें।

मशीन कॉन्फ़िगरेशन जैसी पृष्ठांकित सूचियाँ स्वीकार करती हैं page (डिफ़ॉल्ट 1) और limit (डिफ़ॉल्ट 20, अधिकतम 100) और रिटर्न ए pagination के साथ आपत्ति total और totalPages. बढ़ाने के बजाय अगले पृष्ठ का अनुरोध करें limit टोपी से परे; बड़े मानों को 100 पर क्लैंप किया गया है।

प्राथमिकता कायम रखें

कुंजी-मूल्य एपीआई दूसरी प्रतिक्रिया आकृति और लापता-संसाधन व्यवहार को प्रदर्शित करता है। एक कुंजी जिसे सहेजा नहीं गया है वह 404 लौटाती है:

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

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

PUT के साथ JSON-संगत मान सहेजें। यह एक प्राथमिकता उदाहरण है; यह विश्व स्तर पर ज्यामिति कर्नेल की इकाइयों को नहीं बदलता है।

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

उसी कुंजी को पढ़ने से अद्यतन टाइमस्टैम्प सहित संग्रहीत प्रविष्टि वापस आ जाती है। प्रतिक्रिया किसी प्रोजेक्ट रिकॉर्ड या सफलता लिफाफे में मूल्य को लपेटती नहीं है।

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

उपयोग GET /api/kv?prefix=docs.walkthrough. मेल खाने वाली प्रविष्टियों को सूचीबद्ध करने के लिए, या इसे हटाने के लिए एन्कोडेड कुंजी को हटा दें। स्टोर अपने JSON-संगत डोमेन के बाहर रिक्त कुंजियों, अधिक लंबी कुंजियों और मानों को अस्वीकार करता है। यह कोई क्रेडेंशियल वॉल्ट नहीं है.

विफलताओं को संभालें और पुनः प्रयास करें

उत्पादन ग्राहकों में, जाँच करें response.ok और उचित सफलता या त्रुटि निकाय को डिकोड करें। एक समान लिफाफे पर भरोसा करने से बचें: अकेले इस वॉकथ्रू में एक सरणी, सादे रिकॉर्ड और टैग की गई विफलताएं शामिल हैं।

अगले एकीकरण चरण

उपयोग पूर्ण संदर्भ एक संसाधन का चयन करने के लिए. मशीनिंग समापनबिंदु टूलपाथ को सहेजने से गणना को अलग कर सकेंगे; इतिहास समापन बिंदु वर्किंग-कॉपी परिवर्तनों को कमिट और रिमोट सिंक्रोनाइज़ेशन से अलग करें। एआई संसाधन सत्र पहचानकर्ता और स्ट्रीमिंग नियंत्रण शामिल हैं।

चल रही साइडकार पढ़ें /api/openapi.json एक अलग बिल्ड को एकीकृत करते समय। डाउनलोड करने योग्य दस्तावेज़ स्नैपशॉट चेक-आउट अनुबंध का वर्णन करता है; यह स्थापित नहीं कर सकता कि कौन सी बाइनरी दूसरी मशीन चल रही है।

सभी प्रतिक्रियाएँ एक नज़र में कैप्चर की गईं

इस पृष्ठ पर प्रतिक्रियाएँ एक ताज़ा डेटाबेस के साथ एक वास्तविक साइडकार से ली गई थीं। आपकी मशीन पर पहचानकर्ता और टाइमस्टैम्प अलग-अलग होंगे; आकार और स्थितियाँ नहीं होंगी।

पूरा दौरा एक स्क्रिप्ट के रूप में

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

स्क्रिप्ट का उपयोग करता है sed आईडी निकालने के लिए ताकि उस पर कोई निर्भरता न रहे; साथ jq स्थापित, पसंद करें jq -r .id. इसे डिस्पोजेबल डेटा निर्देशिका के विरुद्ध चलाएँ: यह एक वास्तविक प्रोजेक्ट बनाता है।

दौरे के बाद सफाई करें

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"

प्रोजेक्ट को हटाना उसके चित्र, घटकों, टूलपाथ, इतिहास और वर्कफ़्लो रन में कैस्केड करता है। कुंजी-मान प्रविष्टि स्वतंत्र है और इसे अलग से हटाया जाना चाहिए।

3डी में