الانتقال إلى عنوان API

تستدعي التكاملات الأقدم واجهة API على عنوان Sursa الرئيسي، أي العنوان الذي يفتحه الناس في المتصفح، مثل https://app.sursa.com/v1/…. وأصبح لواجهة API الآن عنوانها الخاص أيضًا: https://api.sursa.com في السحابة، أو https://api.<your domain> في نسختك المثبتة. وهو مصمم للتكاملات: يتوسع أفقيًا خلف موزِّع أحمال، ولا يخدم سوى واجهة API.

الانتقال ليس إلزاميًا. يواصل العنوان الرئيسي خدمة /v1 للتكاملات القائمة، بلا تاريخ انتهاء وبلا إعادة توجيه. انتقل حين يناسبك، لتحصل على مزايا عنوان API، واستخدمه لكل تكامل جديد.

ما يبقى كما هو

المسارات والمعاملات والحقول ورموز الأخطاء والأحداث: الطلب GET /v1/cards هو نفسه على العنوانين.
مفاتيح API. تعمل المفاتيح نفسها، kb_ وkbsrc_، على العنوانين، بالدور ونطاقات الصلاحيات وملف تعريف البيانات نفسها.
مفاتيح عدم التكرار وحدود المعدل والحصص. والطلبات على العنوانين تُحتسب ضمن حصص المؤسسة نفسها.
خطافات الويب. لا تعتمد التسليمات والتواقيع والأسرار على العنوان الذي تستدعيه.
الروابط في الاستجابات. يشير الحقل doc_url في الخطأ إلى هذه البوابة، وتشير الترويسة Link في صفحة القائمة إلى عنوان API، أيًّا كان العنوان الذي تستدعيه.

ما يختلف على عنوان API

على العنوان الرئيسي	على عنوان API
كل نقاط نهاية تطبيق الويب، بما فيها الداخلية	نقاط النهاية الموجودة في مرجع API العام فقط. وأي مسار آخر يجيب بالحالة `404` مع الرمز `api.not_found`.
مفتاح في `X-API-Key` أو `Authorization`، أو ملف تعريف ارتباط لجلسة المتصفح	مفتاح أو رمز وصول OAuth، ويُفضَّل في `Authorization: Bearer`. وتُتجاهل ملفات تعريف الارتباط.
العملية `GET /auth/me`	العملية `GET /v1/me`. ولا تُخدَم المسارات تحت `/auth/`.
وضع «View as» (عرض بصفة) عبر ملف تعريف ارتباط	الترويسة `X-View-As`، للمفاتيح ذات الدور `admin`.
خادم واحد، أو عدد ثابت من الخوادم	عدة خوادم خلف موزِّع أحمال.

الصف الأخير مهم في حالة واحدة فقط: الإجابة المتدفقة من POST /v1/chat. فالتدفق المنقطع يُستأنف من Last-Event-ID على الخادم الذي يكتب الإجابة فقط. إذا كان تكاملك يستأنف التدفقات، فأعطِ كل سؤال قيمة request_id، كي تتلقى إعادة المحاولة على خادم آخر الإجابة المحفوظة بدل إجابة ثانية. انظر استئناف تدفق منقطع.

قبل الانتقال

تحقّق من أن كل استدعاء عام. اسرد المسارات التي يستدعيها تكاملك وابحث عن كل منها في مرجع API، أو قارنها بمواصفة العنوان الجديد:

curl -s https://api.sursa.com/openapi.json \
  | jq -r '.paths | to_entries[] | .key as $p | .value | keys[] | ascii_upcase + " " + $p' \
  | sort > public-operations.txt

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

تحقّق من طريقة المصادقة. إذا كان التكامل يسجّل الدخول بكلمة مرور مستخدم وملف تعريف ارتباط للجلسة، فانقله أولًا إلى مفتاح API. وإذا كان يرسل X-API-Key، فالتحول إلى Authorization: Bearer موصى به لكنه غير إلزامي.

تحقّق من شبكتك. اسمح باتصالات HTTPS الصادرة إلى اسم المضيف الجديد في جدار الحماية والخوادم الوكيلة لديك.

الانتقال خطوة بخطوة

اجعل عنوان URL الأساسي إعدادًا في تكاملك، إن لم يكن كذلك بعد.

جرّب العنوان الجديد بطلب قراءة:

curl https://api.example.com/v1/me -H "Authorization: Bearer $SURSA_API_KEY"

شغّل حزمة الاختبارات الخاصة بتكاملك على العنوان الجديد، بمفتاح اختبار ومجموعة للاختبار.
حوّل جزءًا من حركة الطلبات، مثل عملية معالجة واحدة (worker) أو بيئة واحدة، وراقب 404 api.not_found و401 و5xx في سجلاتك. وتحمل كل استجابة الترويسة X-Request-Id، فاحفظها مع سجلاتك.
حوّل الباقي. أبقِ عنوان URL الأساسي القديم في إعداداتك فترة من الزمن، لتتمكن من العودة إليه في ثوانٍ.

ما تتحقق منه بعد الانتقال

تعيد العملية GET /v1/health على العنوان الجديد قيمة version نفسها كما على القديم.
الترويسات RateLimit موجودة في الاستجابات. وإذا كان تكاملك يبطئ نفسه حسب X-RateLimit-*، فيمكنه مواصلة ذلك: فالنوعان يُرسَلان معًا. انظر حدود معدل الطلبات والحصص.
إذا كان تكاملك يعمل في المتصفح، فلم يعد بحاجة إلى خادم وكيل خاص بك من أجل CORS: عنوان API يسمح بالطلبات من أي أصل، بلا ملفات تعريف ارتباط.