نظرة عامّة على واجهة API

تعيد واجهة بحث Suede نتائج بحث خاصّة وخالية من الإعلانات بصيغة JSON — نفس نتائج الويب والصور والأخبار والفيديو والتسوّق التي تشغّل Suede، من دون إعلانات أو تعقّب، ومن دون الاحتفاظ بسجلّ استعلامات مرتبط بك.

عنوان URL الأساسي

نقطة نهاية عالمية واحدة تخدم كلّ الحسابات:

https://api.suede.io

تُوجَّه الطلبات تلقائيًا إلى أقرب مناطق البنية التحتية — كلّ المناطق تقدّم واجهة البرمجة نفسها، والمَعلمة الاختيارية gl تختار ترجيح النتائج لكلّ استعلام. وليس عليك ضبط أي شيء.

المستكشف التفاعلي

يخدم مضيف واجهة API مرجعًا حيًّا داخل المتصفّح. افتح جذر المضيف (https://api.suede.io/) فيعيد توجيهك إلى المستكشف على /scalar/v1، حيث يكون كلّ نقطة نهاية موثَّقة وقابلة للاستدعاء بمفتاحك الخاصّ. ويوجد وصف OpenAPI القابل للقراءة آليًا على /openapi/v1.json إن أردت توليد عميل أو استيراد واجهة API إلى أداة أخرى.

المصادقة

يجب أن تحمل كلّ طلب مفتاح API خاصّتك بوصفه رمزًا مميّزًا من نوع bearer:

Authorization: Bearer suede_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

أنشئ مفتاحًا في حساب Suede خاصّتك — راجع المصادقة. تتطلّب نقاط نهاية البحث القابلة للفوترة عضويّة Suede نشطة ورصيد ائتمان API موجبًا.

أوّل طلب

curl "https://api.suede.io/v1/search?q=hello+world" \
  -H "Authorization: Bearer $SUEDE_API_KEY"

using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
    new("Bearer", Environment.GetEnvironmentVariable("SUEDE_API_KEY"));
var json = await http.GetStringAsync("https://api.suede.io/v1/search?q=hello+world");
Console.WriteLine(json);

const res = await fetch("https://api.suede.io/v1/search?q=hello+world", {
  headers: { Authorization: `Bearer ${process.env.SUEDE_API_KEY}` },
});
console.log(await res.json());

الاستجابات

الاستجابة الناجحة هي JSON مع HTTP 200. ويستخدم الخطأ غلافًا موحَّدًا:

{ "error": { "type": "invalid_request", "message": "Query parameter 'q' is required.", "request_id": "a1b2c3d4e5f6a7b8" } }

تحمل كلّ استجابة ترويسة X-Request-Id (مُعادةً بوصفها request_id في الأخطاء)؛ اذكرها عند التواصل مع الدعم. يسرد الأخطاء المجموعة الكاملة من الأنواع ورموز الحالة، ويصف حدود المعدّل آليّة التقييد.

الإصدارات

الإصدار الحالي هو v1، ويُبلَغ تحت بادئة المسار /v1. قد تُضاف حقول جديدة إلى الاستجابات دون تغيير الإصدار، لذا حلّل بحذر وتجاهل الحقول غير المعروفة. أمّا أي تغيير كاسر فسيصدر تحت بادئة إصدار جديدة.

نقاط النهاية في لمحة