حالة SDK

تُعدّ واجهة REST API ذات الإصدارات هي واجهة التكامل العامة المدعومة حاليًا. تتوفر الشيفرة المصدرية لعملاء JavaScript وPython وأطر العمل في مستودع المنتج، لكن الحزم غير منشورة حاليًا على npm أو PyPI.

التوفر#

JavaScript بدون SDK#

const response = await fetch("https://makeagent.fast/api/v1/sites?limit=100", {
  headers: {
    Authorization: `Bearer ${process.env.MAF_API_KEY}`,
    Accept: "application/json",
  },
});

const body = await response.json();
if (!response.ok) {
  console.error(body.error.code, body.error.request_id);
  throw new Error(`Make Agent Fast request failed (${response.status})`);
}

for (const site of body.data) console.log(site.id, site.title);

احتفظ بمفتاح API على الخادم. يجب أن تستدعي حزمة المتصفح في React أو Vue أو Svelte الواجهة الخلفية الخاصة بك أو أن تثبّت محمّل التضمين العام؛ ولا يجوز أن تستدعي واجهة الإدارة البرمجية بمفتاح سري.

Python بدون SDK#

import json
import os
import urllib.request

request = urllib.request.Request(
    "https://makeagent.fast/api/v1/sites?limit=100",
    headers={
        "Authorization": f"Bearer {os.environ['MAF_API_KEY']}",
        "Accept": "application/json",
    },
)

with urllib.request.urlopen(request, timeout=20) as response:
    payload = json.load(response)

for site in payload["data"]:
    print(site["id"], site["title"])

التقط الاستثناء urllib.error.HTTPError في بيئة الإنتاج وحلّل محتوى JSON في الاستجابة وفق غلاف الأخطاء المستقر.

العملاء المولَّدون#

لا يفيد توليد العملاء من OpenAPI إلا عندما يحتوي المستند على العمليات والمخططات التي يعتمد عليها تطبيقك. ثبّت المواصفة التي نزّلتها، وولّد العميل في مجلد قابل للمراجعة، وافحص كل فروقات التغييرات قبل الترقية.

curl --fail-with-body https://makeagent.fast/api/openapi.json \
  --output make-agent-fast.openapi.json

لا تعِد توليد العميل ونشره تلقائيًا من الرابط المباشر. فإضافة حقل جديد لا ينبغي أن تعطّل العميل، لكن سلوك المولِّد وأسماء الدوال المولَّدة قد يتغيران مع ذلك.

ما يجب أن يتضمنه إصدار SDK عام#

قبل اعتبار أي عميل معاينة متاحًا، يجب أن يتوفر فيه ما يلي:

• صفحة عامة في سجل الحزم وإصدار دلالي (semantic version) غير قابل للتغيير.
• إرشادات التثبيت والترقية وبيئات التشغيل المدعومة.
• نماذج مكتوبة الأنواع للطلبات والاستجابات مولَّدة من عقد API الكامل.
• أخطاء منظَّمة تحتفظ برمز حالة HTTP ومعرّف الطلب.
• أدوات مساعدة للترقيم الصفحي تتعامل مع المؤشرات (cursors) على أنها مبهمة.
• دعم صريح لمفتاح عدم التكرار (idempotency key) في عمليات التعديل.
• اختبارات CI على عقد /api/v1 الحالي وسجل تغييرات منشور.

إلى أن تتحقق هذه الشروط، استخدم أمثلة REST في البدء السريع لـ API ووصفات API.