إرشادات واجهة برمجة التطبيقات (API) مع الاستجابات الملتقطة

البيئة والاستجابات الملتقطة

تم التقاط الاستجابات في هذه الصفحة من المسارات السايدكار الفعلية في 15 أكتوبر 2026 باستخدام apps/sidecar/test/helpers.ts. يقوم هذا الحزام ببناء معالجات التطبيق باستخدام قاعدة بيانات SQLite مُرحَّلة في الذاكرة، ودليل ملفات يمكن التخلص منه، ومضيف الذكاء الاصطناعي المباشر، وبدون مكالمات للموفر. تمر الطلبات عبر جهاز توجيه HTTP قيد التشغيل؛ لا يستخدم هذا التشغيل مشغل Tauri أو مآخذ الشبكة أو TLS أو الهاتف المقترن.

هيئات الاستجابة أدناه غير محررة. وبالتالي فإن المعرفات والطوابع الزمنية تنتمي إلى هذا التشغيل القابل للتصرف. يقوم المثيل الخاص بك بإرجاع القيم الخاصة به. استخدم معرف المشروع الذي تم إرجاعه بواسطة طلب الإنشاء الخاص بك بدلاً من إعادة استخدام المعرف الذي تم التقاطه.

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"

[]

الاستجابة عبارة عن مصفوفة عادية، بدون ملف 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"
}

احفظ قيمة متوافقة مع JSON باستخدام PUT. وهذا مثال تفضيل؛ لا يغير وحدات نواة الهندسة عالميًا.

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د