واجهة API

تستجيب بعض أجزاء موقعك للطلبات بدلًا من عرض صفحة: نموذج تواصل يحفظ رسالة، أو صفحة دفع تطلب من Stripe تحصيل دفعة، أو مهمة ترسل تذكيرات الغد. كل جزء منها هو مسار في كود موقعك، ويتيح لك عرض API تجربة أي منها دون مغادرة المحرر.

فتح العرض

عندما يحتوي موقعك على مسارات، يظهر مفتاح تبديل الصفحات | API أعلى لوحة الصفحات. انقر على API لرؤيتها.

تُنظَّم القائمة مثل صفحاتك، بمستوى واحد لكل جزء من العنوان:

• يعرض المسار الذي يستجيب بطريقة واحدة طريقته في صف مستقل، مثل GET بجوار health. انقر على الصف لفتحه.
• يتوسع المسار الذي يستجيب بعدة طرق ليعرض صفًا لكل طريقة، مثل GET وPOST وDELETE.
• تجمع المجلدات المسارات التي تشترك في بداية عنوانها.
• تظهر أيضًا خريطة موقعك وملف robots.txt وملف بيان التطبيق وصور المشاركة الاجتماعية، لأن الكود ينشئها.

في المواقع التي تحتوي على مسارات كثيرة، يظهر حقل تصفية نقاط النهاية في الأعلى.

يمكنك أيضًا كتابة عنوان يبدأ بـ /api/ في شريط العنوان أعلى المحرر، أو اختيار مسار من القائمة التي تفتح أسفله. عند كتابة عنوان كامل مثل /api/tools/figma، يُفتح المسار وتُملأ القيمة figma تلقائيًا.

على الهاتف، افتح قائمة الموقع في الأعلى واختر API، أو اختر مسارًا من قائمة الصفحات.

إرسال طلب

اختر طريقة ليتحول محتوى مساحة العرض إلى عرض API. يعرض العنوان في الأعلى ما سيُرسَل بالضبط، ويتحدث أثناء إدخال القيم.

• يرسل المعاينة الطلب إلى المسودة التي تعمل عليها. ويرسله مباشر إلى موقعك المنشور.
• يرسل إرسال الطلب. ويمكنك أيضًا استخدام ⌘↵ / Ctrl+Enter.

المعلمات

هي القيم التي يقرأها المسار من عنوانه. قيم المسار هي الأجزاء بين الأقواس، مثل [id]، وتحمل علامة مطلوب. أما قيم الاستعلام فهي القيم التي تأتي بعد ? ويبحث عنها المسار. انقر على إضافة معلمة لإرسال معلمة غير مدرجة.

المحتوى

لطرق POST وPUT وPATCH وDELETE. تظهر الحقول التي يقرأها المسار مسبقًا، لذا املأها كما تملأ نموذجًا. انتقل إلى JSON لكتابة المحتوى بنفسك. إذا كان المسار يقرأ نموذجًا، فستظهر حقول نموذج تُرسَل بالطريقة نفسها التي يرسل بها المتصفح النماذج.

الترويسات

معلومات إضافية تُرسَل مع الطلب، مثل رمز تسجيل الدخول. انقر على إضافة ترويسة لإضافة واحدة.

قراءة الاستجابة

تظهر الحالة أولًا، مع مدة الطلب وحجم الاستجابة. وأسفلها:

• يعرض المحتوى ما عاد بصيغة سهلة القراءة: JSON ملوّن، وXML وHTML منسّقان (مع عرض الصفحة لمحتوى HTML)، وجدول لبيانات CSV، وصور لمحتوى الصور.
• يسرد الترويسات الترويسات التي أعادها المسار.
• يعرض وحدة التحكم ما طبعه خادم موقعك أثناء الاستجابة. ويعمل مع الطلبات المُرسَلة إلى المعاينة.

يظهر زر تنزيل للمسار الذي يرسل ملفًا، مثل تصدير CSV أو صورة مولّدة. ويعرض المسار الذي يعيد توجيه الزوار الوجهة، مع زر فتح الصفحة إذا كانت صفحة على موقعك.

انقر على الساعة لرؤية الطلبات التي أرسلتها في هذه الجلسة وفتح أي منها مجددًا.

عند حدوث خطأ

إذا تعطل الكود أثناء الاستجابة، يعرض API الخطأ وسطر الكود الذي حدث فيه.

• يفتح فتح الكود ذلك الملف في محرر الكود.
• يبدأ إصلاح بالذكاء الاصطناعي محادثة تتضمن الخطأ وما طبعه الخادم، ليتمكن الذكاء الاصطناعي من إصلاحه.

طلبات المستخدمين المسجلين

لا تستجيب بعض المسارات إلا لمن سجّلوا الدخول. أرسل طلبًا إلى مسار تسجيل الدخول في موقعك أولًا، باستخدام بريد إلكتروني وكلمة مرور من موقعك: يحتفظ عرض API بملفات تعريف الارتباط التي يعيّنها موقعك ويرسلها مع طلباتك التالية، كما يفعل المتصفح. تظهر ضمن الترويسات باسم Cookie، مع خيار مسح لتسجيل الخروج.

يمكنك أيضًا إضافة ترويسة Authorization بنفسك إذا كانت مساراتك تستخدم الرموز.

المهام المجدولة والمدفوعات

لا تحتاج إلى نسخ أي أسرار لاختبار ما يلي:

• تتحقق المسارات التي تعمل وفق جدول زمني من سر يحتفظ به موقعك. ويرسله عرض API نيابة عنك.
• تتحقق خطافات الويب في Stripe من التوقيع. يملأ عرض API المحتوى مبدئيًا بحدث اختبار من Stripe ويوقّعه باستخدام السر الخاص بموقعك. تُرسَل أحداث الاختبار الموقّعة إلى المعاينة فقط، لذا لا يؤثر الاختبار مطلقًا في الطلبات الحقيقية على موقعك المنشور.

إضافة مسار

انقر على + أعلى لوحة الصفحات أثناء وجودك في API. واختر نقطة نهاية جديدة من القائمة عندما تكون في الصفحات.

• المسار هو عنوان المسار بعد /api/. استخدم [id] لجزء متغير، مثل tools/[id]/reviews.
• الطرق هي الطرق التي يستجيب بها. اختر ما تحتاج إليه منها.
• يتيح الوصف للذكاء الاصطناعي كتابة المسار في محادثة جديدة. أما ملف فارغ فينشئ ملفًا فارغًا لتكتب الكود بنفسك.

يُفتح المسار الجديد في عرض API بمجرد إنشائه، لتتمكن من تجربته فورًا.

معلومات مفيدة

• لكل طلب مهلة قدرها 12 ثانية. إذا ظل المسار يرسل البيانات بعد ذلك، فسيظهر ما وصل حتى تلك اللحظة.
• يعرض API ما يصل إلى 512 KB من الاستجابة، ويمكن تنزيل ملفات يصل حجمها إلى 5 MB.
• يمكنك تشغيل 3 طلبات في الوقت نفسه، وإرسال ما يصل إلى 30 طلبًا في الدقيقة.
• تبقى طلباتك وسجلّك وملفات تعريف الارتباط حتى تعيد تحميل المحرر.
• يتطلب الإرسال إلى مباشر أن يكون موقعك منشورًا.