DEV Community

Cover image for كيفية استخدام Zuplo API؟
Yusuf Khalidd
Yusuf Khalidd

Posted on • Originally published at apidog.com

كيفية استخدام Zuplo API؟

إذا كنت قد قرأت عن Zuplo وترغب في إطلاق مشروع حقيقي باستخدامه، فهذا الدليل العملي يوضح لك الخطوات الأساسية من البداية للنشر والاختبار. ستتعلم كيف تنشئ مشروع Zuplo، وتعرف المسارات، وتضيف مصادقة وتحديد معدل، وتكتب سياسة TypeScript مخصصة، وتنشر إلى الحافة، وتختبر كل شيء باستخدام Apidog.

جرّب Apidog اليوم

بحلول نهاية الدليل سيكون لديك بوابة API جاهزة أمام مصدرك، مع مصادقة وتحديد معدل، وبوابة مطورين، وسير عمل Git متكامل مع CI. يمكنك إنجاز جميع الخطوات في حوالي 30 دقيقة.

إذا كنت لا تزال تقرر ما إذا كان Zuplo مناسبًا لك، اطلع على منشورنا المصاحب: ما هي بوابة API Zuplo. للمزيد من التفاصيل، راجع وثائق Zuplo.

ملخص سريع

  • سجل في portal.zuplo.com أو أنشئ مشروعًا محليًا باستخدام npm create zuplo.
  • حدد المسارات في config/routes.oas.json وأعد توجيهها لمصدرك عبر URL Forward Handler.
  • أضف سياسات مثل مصادقة مفتاح API وتحديد المعدل من ملف المسار أو مصمم المسارات.
  • اكتب منطقًا مخصصًا عبر وحدات TypeScript في modules/.
  • ادفع إلى فرع Git للنشر؛ ادمج للنشر إلى الإنتاج عبر أكثر من 300 موقع Edge.
  • اختبر كل مسار باستخدام Apidog قبل إطلاق الإنتاج.
  • الأسعار: مجاني حتى 100 ألف طلب شهريًا؛ خطة Builder بـ 25 دولار شهريًا.

المتطلبات الأساسية

قبل البدء تأكد من توفر:

  • حساب Zuplo
  • مصدر API (استخدم https://echo.zuplo.io للاختبار)
  • Node.js 18 أو أعلى (إذا كنت ستستخدم CLI)

للتطوير المحلي، استخدم محرر أكواد مثل VS Code مع إضافة TypeScript، ويمكنك دمجه مع إضافة Apidog لـ VS Code لإطلاق الطلبات مباشرة.

الخطوة 1: إنشاء مشروع Zuplo

الخيار أ: البوابة أولاً

  1. سجل الدخول إلى portal.zuplo.com.
  2. أنشئ مشروع جديد باسم مثل acme-gateway.
  3. اختر "مشروع فارغ".
  4. ستظهر لك شجرة ملفات البداية في تبويب الكود.

Zuplo Portal Start

المشروع يرتبط بمستودع Git مُدار افتراضيًا. يمكنك ربط GitHub أو GitLab أو Bitbucket أو Azure DevOps لاحقًا.

الخيار ب: CLI أولاً

ابدأ مشروعك محليًا:

npm create zuplo@latest -- --name acme-gateway
cd acme-gateway
npm install
npm run dev
Enter fullscreen mode Exit fullscreen mode

سيعمل خادم التطوير على المنفذ 9000، مع مصمم المسارات على http://localhost:9100. أي تغيير يتم إعادة تحميله فورًا.

عند الاستعداد للنشر، اربط المشروع بحسابك:

npx zuplo link
Enter fullscreen mode Exit fullscreen mode

ثم للنشر:

npx zuplo deploy
Enter fullscreen mode Exit fullscreen mode

الخطوة 2: تعريف المسار الأول

افتح config/routes.oas.json وأضف مسار GET:

{
  "openapi": "3.1.0",
  "info": { "title": "Acme Gateway", "version": "1.0.0" },
  "paths": {
    "/v1/products": {
      "get": {
        "summary": "List products",
        "operationId": "list-products",
        "x-zuplo-route": {
          "corsPolicy": "anything-goes",
          "handler": {
            "export": "urlForwardHandler",
            "module": "$import(@zuplo/runtime)",
            "options": {
              "baseUrl": "${env.ORIGIN_URL}"
            }
          },
          "policies": { "inbound": [] }
        },
        "responses": {
          "200": { "description": "Success" }
        }
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode
  • استخدم متغير البيئة ORIGIN_URL من إعدادات المشروع أو من config/.env.
  • جرب الوصول إلى http://localhost:9000/v1/products وسترى استجابة معكوسة من المصدر.

الخطوة 3: إضافة مصادقة مفتاح API

أضف سياسة المصادقة في المسار:

"policies": {
  "inbound": ["api-key-auth"]
}
Enter fullscreen mode Exit fullscreen mode

ثم عرف السياسة في config/policies.json:

{
  "name": "api-key-auth",
  "policyType": "api-key-inbound",
  "handler": {
    "export": "ApiKeyInboundPolicy",
    "module": "$import(@zuplo/runtime)",
    "options": {
      "allowUnauthenticatedRequests": false
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

لإنشاء مستهلك ومفتاح API:

  1. اذهب إلى Services > API Key Service في البوابة.
  2. "إنشاء مستهلك" (subject مثل acme-customer-1).
  3. انسخ مفتاح API.

اختبر بدون رأس المصادقة:

curl -i https://YOUR-PROJECT.zuplo.app/v1/products
# HTTP/2 401
Enter fullscreen mode Exit fullscreen mode

ومع الرأس:

curl -i https://YOUR-PROJECT.zuplo.app/v1/products \
  -H "Authorization: Bearer YOUR_API_KEY"
# HTTP/2 200
Enter fullscreen mode Exit fullscreen mode

يمكنك استيراد الـ OpenAPI إلى Apidog واستخدام متغيرات البيئة لتجربة جميع المسارات.

الخطوة 4: تحديد معدل المسار

أضف سياسة تحديد المعدل:

"policies": {
  "inbound": ["api-key-auth", "rate-limit-by-key"]
}
Enter fullscreen mode Exit fullscreen mode

واضبطها في config/policies.json:

{
  "name": "rate-limit-by-key",
  "policyType": "rate-limit-inbound",
  "handler": {
    "export": "RateLimitInboundPolicy",
    "module": "$import(@zuplo/runtime)",
    "options": {
      "rateLimitBy": "sub",
      "requestsAllowed": 60,
      "timeWindowMinutes": 1
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

اختبر بإرسال 70 طلبًا في حلقة:

for i in {1..70}; do
  curl -s -o /dev/null -w "%{http_code}\n" \
    https://YOUR-PROJECT.zuplo.app/v1/products \
    -H "Authorization: Bearer YOUR_API_KEY"
done | sort | uniq -c
Enter fullscreen mode Exit fullscreen mode

ستجد 60 استجابة 200 و10 استجابات 429.

الخطوة 5: التحقق من حمولات الطلب

أضف مسار POST مع التحقق من الجسم:

"/v1/products": {
  "post": {
    "summary": "Create product",
    "operationId": "create-product",
    "requestBody": {
      "required": true,
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": ["name", "priceCents"],
            "properties": {
              "name": { "type": "string", "minLength": 1 },
              "priceCents": { "type": "integer", "minimum": 1 },
              "category": { "type": "string", "enum": ["food", "drink"] }
            }
          }
        }
      }
    },
    "x-zuplo-route": {
      "handler": { /* نفس المعالج */ },
      "policies": {
        "inbound": [
          "api-key-auth",
          "rate-limit-by-key",
          "validate-request"
        ]
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

أضف سياسة التحقق:

{
  "name": "validate-request",
  "policyType": "open-api-request-validation-inbound",
  "handler": {
    "export": "OpenApiRequestValidationInboundPolicy",
    "module": "$import(@zuplo/runtime)",
    "options": {
      "validateBody": "reject"
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

أي طلب POST غير صحيح يُرفض بـ 400. استخدم Apidog لتجربة سيناريوهات الطلب بسهولة.

الخطوة 6: سياسة TypeScript مخصصة

أنشئ ملف modules/tiered-cache.ts:

import { ZuploRequest, ZuploContext, HttpProblems } from "@zuplo/runtime";

interface PolicyOptions {
  paidPlanHeader: string;
  paidMaxAge: number;
}

export default async function (
  response: Response,
  request: ZuploRequest,
  context: ZuploContext,
  options: PolicyOptions,
): Promise<Response> {
  const plan = request.user?.data?.plan ?? "free";

  if (plan === "free") {
    response.headers.set("Cache-Control", "no-store");
  } else {
    response.headers.set(
      "Cache-Control",
      `public, max-age=${options.paidMaxAge}`,
    );
  }

  context.log.info(`Cache header set for plan=${plan}`);
  return response;
}
Enter fullscreen mode Exit fullscreen mode

عرف السياسة في config/policies.json:

{
  "name": "tiered-cache",
  "policyType": "custom-code-outbound",
  "handler": {
    "export": "default",
    "module": "$import(./modules/tiered-cache)",
    "options": {
      "paidPlanHeader": "x-plan",
      "paidMaxAge": 300
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

ثم أضفها إلى المسار:

"policies": {
  "inbound": ["api-key-auth", "rate-limit-by-key"],
  "outbound": ["tiered-cache"]
}
Enter fullscreen mode Exit fullscreen mode

يمكنك اختبار السياسة بوحدة باستخدام Vitest أو Jest.

الخطوة 7: النشر إلى الحافة

ادفع التغييرات إلى Git:

git add .
git commit -m "Add products gateway with auth, rate limit, and tiered cache"
git push origin feature/products-gateway
Enter fullscreen mode Exit fullscreen mode

ستحصل على بيئة معاينة لكل فرع مع URL خاص. اختبرها باستخدام Apidog عبر تعيين البيئة الجديدة.

للنشر إلى الإنتاج:

git checkout main
git merge feature/products-gateway
git push origin main
Enter fullscreen mode Exit fullscreen mode

خلال دقيقة واحدة سيكون الإصدار الجديد نشطًا على جميع مواقع الحافة.

الخطوة 8: إنشاء بوابة المطورين

البوابة متوفرة على https://YOUR-PROJECT.developers.zuplo.com، وتشمل:

  • صفحة لكل مسار مع المخطط والتوثيق وأمثلة أكواد.
  • إصدار مفتاح API ذاتي الخدمة.
  • تحكم في العلامة التجارية من الإعدادات.

يمكنك تخصيص البوابة عبر مستودع GitHub الخاص ببوابة المطورين، أو البقاء على النسخة المستضافة.

الخطوة 9: اختبار كل شيء باستخدام Apidog

بعد النشر، تأكد من اختبار كل مسار وسياسة باستخدام Apidog.

Apidog Interface

سير العمل المقترح:

  1. استورد OpenAPI من https://YOUR-PROJECT.zuplo.app/openapi.
  2. أنشئ بيئات لـ local، وpreview، وproduction مع متغيرات base_url وapi_key.
  3. احفظ ثلاثة طلبات لكل مسار: ناجح، فشل المصادقة، تخطي تحديد المعدل.
  4. استخدم سيناريوهات Apidog لربط العمليات (إنشاء، قائمة، حذف).
  5. أنشئ أمثلة أكواد بلغتك وانسخها إلى مستنداتك.

إذا كنت تنتقل من Postman، اطلع على دليل اختبار API بدون Postman.

أسئلة شائعة حول Zuplo

كيف أبدل المسار بين البيئات؟

استخدم متغيرات البيئة مثل ORIGIN_URL في إعدادات البيئة أو ملف .env، وارجع إليه في المعالج.

هل يمكن تشغيل Zuplo بدون إنترنت؟

نعم، عبر npm run dev محليًا. السياسات تعمل محليًا باستثناء خدمة مفتاح API المدارة التي تتطلب ربط سحابي عبر npx zuplo link.

كيف أتراجع عن نشر سيء؟

نفذ git revert لالتزام الدمج وادفع، وسيعيد Zuplo نشر الحالة السابقة.

ماذا يحدث للطلبات أثناء النشر؟

النشر ذري؛ الطلبات الحالية تستكمل على الإصدار القديم والجديدة تذهب للإصدار الجديد. لا يوجد Downtime.

هل يدعم Zuplo gRPC وWebSockets؟

نعم، يدعم WebSocket transparently وgRPC عبر معالج مخصص. REST وGraphQL هما الأكثر استخدامًا.

كيف أكشف API لـ AI Agents؟

أضف معالج MCP لمساراتك وخصص السياسات. راجع دليل Zuplo MCP.

ما تكلفة الإنتاج؟

الطبقة المجانية: 100 ألف طلب/شهر. Builder: مليون طلب بـ 25$. تفاصيل أكثر في تسعير Zuplo.

الخاتمة

الآن لديك بوابة Zuplo متكاملة مع مصادقة، وتحديد معدل، والتحقق، وسياسة TypeScript مخصصة، وبوابة مطورين، ونشر عبر Git إلى الحافة. حلقة الاختبار هي الضمان الأساسي للثبات: اختبر كل معاينة عبر Apidog قبل الدمج، لتكتشف أي أخطاء قبل الإنتاج. حمّل Apidog الآن واربطه ببوابتك.

Top comments (0)