نقطة نهاية API، أو نقطة الوصول، هي العنوان الدقيق الذي تستقبل فيه واجهة برمجة التطبيقات (API) الطلبات وترد بالاستجابات. وهي النقطة التي تتصل فيها التطبيقة بالخادم لطلب البيانات أو تنفيذ أمر. في دليل نُشر على مدونتها، تشرح شركة إيلفين لابس هذا العمل بناءً على واجهتها ElevenAPI.
الطلبات والاستجابات والمسارات
نقطة النهاية هي موقع رقمي تستخدمه واجهة برمجة التطبيقات لاستقبال الطلبات وإرسال الردود. تصل التطبيقات العميلة إلى موارد الخادم عبر عنوان URL مرتبط بهذه النقطة. ويربط كل مسار بين طريقة HTTP، وهي بروتوكول اتصال الويب، ومسار مورد معين.
يتبع التبادل عادة أربع خطوات. أولاً، يرسل العميل طلب HTTP يتضمن طريقة وترويسات وربما معلمات وجسم بيانات. ثم يتحقق الخادم من بيانات الاعتماد وأذونات الوصول، ويستعلم قواعد بياناته أو ينفذ منطق العمل. بعد ذلك، يعيد حمولة مفيدة بتنسيق JSON، وهو تنسيق بيانات منظم، مصحوبة برمز حالة HTTP. وأخيراً، تستفيد التطبيقة العميلة من هذه البيانات.
غالباً ما تُستخدم مصطلحات API ونقطة النهاية وعنوان URL معاً، لكنها لا تشير إلى نفس الشيء. فـ API هي مجموعة القواعد وعقود البيانات التي تتيح لتطبيقين التواصل. أما نقطة النهاية فهي نقطة دخول محددة، في حين أن عنوان URL هو العنوان المكتوب الكامل الذي يسمح بتحديد موقعها على الشبكة. تحتوي واجهة برمجة التطبيقات على عدة نقاط نهاية، وقد يتضمن عنوان URL بروتوكولاً واسم نطاق ومساراً ومعلمات استعلام.
في واجهة برمجة تطبيقات REST، تقرأ طلبات GET البيانات دون تعديل موارد الخادم، بينما تنشئ طلبات POST بياناتاً أو تُطلق إجراءات. وتُستخدم طلبات PUT أو PATCH لتعديل السجلات الموجودة، وطلبات DELETE لحذفها. وفقاً للدليل، تعتمد ElevenAPI بشكل أساسي على GET وPOST، مع إضافة نقاط نهاية للبث المباشر وWebSocket للصوت في الوقت الفعلي. على سبيل المثال، يسترجع الطلب GET https://api.elevenlabs.io/v1/models قائمة نماذج توليف الصوت المتاحة وقدراتها. بينما يرسل الطلب POST https://api.elevenlabs.io/v1/text-to-speech/{voice_id} نصاً ومعرّف نموذج، ويعيد صوتاً عبر البث المباشر.
تأمين نقاط النهاية
يحمل كل طلب المفتاح السري في ترويسة xi-api-key. يجب أن تبقى هذه المفاتيح طويلة الأجل على خوادم آمنة ولا تظهر أبداً في الكود من جانب العميل، كما في المتصفح أو تطبيق الهاتف المحمول. بالنسبة لاتصالات WebSocket من جانب العميل، يولد الخادم رمزاً لمرة واحدة، ينتهي صلاحيته بعد 15 دقيقة ويُستهلك عند أول استخدام.
يوصي الدليل أيضاً بإنشاء مفاتيح منفصلة للتطوير والمرحلة ما قبل الإنتاج والإنتاج. يمكن تقييد كل مفتاح لنقاط نهاية معينة، على سبيل المثال، للتحويل الصوتي لمفتاح لا يحتاج إلى التوليف. يمكن تعيين حصص ائتمانية لكل مفتاح، ويمكن لحسابات المؤسسات تقييد الاستخدام لعناوين IP معينة، وهي ميزة قيد العرض التجريبي. عندها تُرفض الطلبات القادمة من عنوان آخر بخطأ HTTP 403. وفقاً للمصدر، تعتمد حدود معدل النقل على المنافسة، أي عدد عمليات التوليد المتزامنة، وليس على حصة في الدقيقة.
الاختبار والمراقبة
يسمح اختبار نقطة نهاية من البداية بالتحقق من المصادقة والتواصل قبل كتابة منطق التطبيق. يكفي طلب GET إلى https://api.elevenlabs.io/v1/models، مع ترويسة xi-api-key، للتحقق من صحة بيانات الاعتماد ووصول الشبكة. وفقاً للدليل، لا يستهلك هذا الاختبار أي ائتمانات تُفوتر على الحساب.
يجب أيضاً مراقبة أخطاء HTTP 429. يشير الخطأ too_many_concurrent_requests إلى أن الحساب وصل إلى حد المنافسة في خطته: يجب الانتظار حتى تنتهي الطلبات الجارية أو الترقية إلى خطة أعلى. بينما يشير الخطأ system_busy إلى ازدحام مؤقت في المنصة، وعادة ما تنجح محاولة إعادة الطلب.
