تصميم REST APIs لتطبيقات الهاتف وتكاملات الشركاء

تمثل API وعدًا تعاقديًا. ما إن يعتمد عليها تطبيق هاتف أو نظام شريك حتى لا يعود تغييرها بحرية تغيير شاشة داخلية. تعرض مشاريعنا واجهات لتطبيقات المندوبين والفرق الميدانية وتكاملات الشركاء في منصات الشحن والحجز. هذه ممارسات تساعد على الوفاء بذلك الوعد.

صمم الموارد لا الشاشات، وأصدر نسخة مبكرًا

ابنِ API حول مفاهيم العمل مثل الطلبات والشحنات والعملاء والفواتير، مع أسماء جمع متسقة وطرق HTTP ورموز حالة مناسبة. لا تجعل النقاط النهائية انعكاسًا لحاجة شاشة اليوم وحدها، فالإصدار المقبل سيحتاج غيرها.

• GET /api/v1/shipments يعرض الشحنات مع المرشحات والترقيم.
• POST /api/v1/shipments ينشئ شحنة.
• GET /api/v1/shipments/{id} يعرض شحنة بعينها.
• PATCH /api/v1/shipments/{id} يحدث جزءًا منها.

عندما لا يلائم الفعل نمط الموارد، مثل إلغاء شحنة، يكون endpoint واضح الاسم أفضل من تحميل التحديث معنى إضافيًا.

أصدر نسخة منذ اليوم الأول

يصعب تحديث تطبيقات الهاتف فورًا؛ فبعض المستخدمين يؤجلون الترقية. ضع رقم إصدار في المسار مثل /api/v1 من أول إصدار. اجعل التغييرات داخل النسخة إضافية: حقول اختيارية أو نقاط جديدة أو قيم يمكن للعميل القديم تجاهلها. عند كسر التوافق، أصدر نسخة جديدة وأبق القديمة فترة معلنة.

استخدم API resources لمخرجات مستقرة

توفر موارد Eloquent في Laravel موضعًا واحدًا يحدد محتوى الاستجابة. تمنع تسرب تغييرات الأعمدة الداخلية إلى العقد وتسهّل إخفاء حقول بحسب الدور.

المصادقة والتفويض

اختر الآلية المناسبة للعميل. تلائم رموز Laravel Sanctum تطبيقات الهاتف الداخلية وواجهات SPA. أما أنظمة الشركاء التي تتصل من خوادم فتحتاج مفاتيح طويلة العمر يمكن تدويرها وإلغاؤها منفردة، مع نطاق صلاحيات يحدد ما تتيحه.

فوّض كل طلب

تحدد المصادقة هوية المتصل، أما التفويض فيحدد ما يجوز له الوصول إليه. تحقق من الملكية والدور في كل endpoint باستخدام policies، ولا تثق بمعرّف يرسله العميل قبل التأكد من تبعيته له. وفي الأنظمة متعددة المستأجرين قيد كل استعلام بالمستأجر.

حدد المعدل لكل عميل

طبّق حدودًا لكل رمز أو مفتاح وأعد ترويسات واضحة. ينبغي ألا يبطئ سكربت شريك معطوب مستخدمي الهاتف.

اجعل القوائم والأخطاء متوقعة

رقّم كل قائمة قابلة للنمو

أعد القوائم ببنية موحدة وحد أقصى لحجم الصفحة. تكون الصفحات بالمؤشر أكثر ثباتًا للتدفقات سريعة التغير من أرقام الصفحات، لأن السجلات الجديدة لا تحرك النتائج تحت يد المستخدم.

استخدم صيغة خطأ موحدة

يجب أن يعالج العميل الإخفاقات بطريقة واحدة: رمز HTTP المناسب، ورمز آلي قصير، ورسالة مقروءة. وفي أخطاء التحقق أدرج أخطاء الحقول ببنية متوقعة.

{
  "message": "The given data was invalid.",
  "code": "validation_failed",
  "errors": {
    "phone": ["The phone field is required."]
  }
}

لا تكشف traces أو SQL أو المسارات الداخلية. سجلها على الخادم وأعد مرجعًا يستطيع العميل ذكره للدعم.

صمم للشبكات غير الموثوقة

قد يفقد مستخدم الهاتف الإشارة، وقد يعيد الشريك الطلب إذا لم يتلق ردًا. توقع الطلبات المكررة:

1. مفاتيح Idempotency: اطلب مفتاحًا فريدًا للطلبات التي تنشئ سجلات مالية أو طلبات. أعد النتيجة الأصلية عند تكراره بدل إنشاء سجل ثانٍ.
2. حمولات صغيرة: أعد ما تحتاجه الشاشة فقط، وادعم عرضًا خفيفًا للقوائم.
3. طلبات شرطية: استخدم ETags أو الطوابع الزمنية لتجنب تنزيل بيانات لم تتغير.
4. مزامنة ملائمة للعمل دون اتصال: اقبل دفعات التغييرات مع أوقات العميل وحدد قواعد تعارض واضحة.

Webhooks للشركاء

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

وثّق واختبر

API غير موثقة عبء دعم. انشر وصف OpenAPI أو مرجعًا واضحًا بطلبات واستجابات نموذجية، واحتفظ به في المستودع نفسه لمراجعة تغييرات الشيفرة والوثائق معًا. أضف اختبارات ميزات تستدعي endpoints الفعلية وتتحقق من رموز الحالة والبنية والصلاحيات؛ فهي تحرس العقد من التغييرات غير المقصودة.

إذا كنت تخطط لتطبيق هاتف أو بوابة شركاء أو تكامل بين أنظمتك، نصمم API ونبنيها معك. شاهد مشاريعنا وخدماتنا أو تواصل مع نارمار.