الـ API الجيد ليس مجرد مجموعة Endpoints. تعرف على القرارات التي تجعل الـ API منظمًا وآمنًا وأسهل في التطوير والصيانة.
ينجح الـ API عندما يستطيع التطبيق المستهلك توقع النتيجة، خصوصًا عند حدوث خطأ. أبدأ بمسارات العمل الفعلية لفريقي الويب والموبايل: ما البيانات التي تحتاجها الشاشة، ومتى تتغير، وما العمليات التي قد يعيد العميل إرسالها. أسماء الـ Endpoints تأتي بعد فهم هذا العقد.
نظم الموارد والاستجابات
استخدم أسماء موارد واضحة مع HTTP method مناسب: GET للقراءة وPOST للإنشاء وPATCH للتعديل وDELETE للحذف عندما يكون منطقيًا. يجب أن تميز Status Codes بين الإنشاء الناجح وخطأ Validation وعدم وجود صلاحية والسجل غير الموجود. شكل استجابة ثابت يوفر على كل عميل كتابة استثناءات لكل Endpoint.
أخطاء Validation يجب أن تحدد الحقول برسائل مفيدة. لا تعرض Stack Trace أو أسماء الجداول أو تفاصيل الاستثناء للمستخدم. التوثيق الجيد يتضمن أمثلة للنجاح والفشل ومتطلبات المصادقة والحقول التي يحق للعميل الاعتماد عليها.
جهز قوائم البيانات للنمو
Pagination تمنع القائمة الصغيرة اليوم من التحول إلى استجابة ضخمة غدًا. حدد الفلاتر والترتيب المدعومين صراحة، ولا تجعل أسماء الأعمدة تأتي مباشرة من Query Parameters. في الموبايل راعِ الاتصال البطيء وقلل الطلبات المتسلسلة إذا أمكن تقديم Resource مناسب.
احمِ العقد بين التطبيقات
Authentication تحدد هوية المتصل، وAuthorization تحدد ما يستطيع فعله بهذا السجل تحديدًا. Rate limiting يحمي العمليات الحساسة أو المكلفة، لكن قيمته يجب أن تناسب المستخدم وطبيعة العمل. سجّل معلومات تساعد على التحقيق دون حفظ Tokens أو بيانات خاصة في الـ Logs.
العمليات التي قد تُعاد، خصوصًا الدفع أو إنشاء الطلبات، تحتاج استراتيجية Idempotency. انتهاء مهلة الاتصال لا يعني بالضرورة أن السيرفر لم يكمل العملية. اجعل الإعادة آمنة ووفر طريقة لمعرفة الحالة النهائية.
طوّر الـ API دون كسر العملاء
Versioning مفيد عندما يصبح التغيير غير متوافق، لكنه ليس بديلًا لإدارة التغيير. إضافة حقول جديدة عادة أسهل من تغيير اسم حقل قائم. أعلن عن إلغاء الخصائص بوضوح واختبر التطبيقات القديمة مع الإصدارات الجديدة.
الـ REST API الجيد اتفاق واضح ومستقر بين الفرق. التسمية والأمان والأخطاء المتوقعة وخطة التطور أهم من عدد الـ Endpoints.
مثال على مورد الطلبات
قد ينشئ تطبيق العميل طلبًا باستخدام POST ثم يتلقى المعرف والحالة ويقرأه لاحقًا باستخدام GET. لوحة الإدارة تعرض الطلبات بفلاتر محددة للحالة والتاريخ، وتسمح لمدير بتغيير حالة طلب بعد التحقق من الصلاحية والبيانات. يجب أن يكون معنى كل حالة واحدًا في التطبيقين، دون كشف أسماء الجداول في الاستجابة.
افترض انقطاع الاتصال بعد إنشاء الطلب. إذا استُخدم Idempotency Key يمكن للإعادة أن تعيد الطلب الأصلي بدل إنشاء نسخة ثانية. بعدها يقرأ العميل الحالة بدل التخمين إذا بدأ الدفع أو التسليم. هذا السلوك يحتاج توثيقًا واختبارًا.
اجعل الخطأ قابلًا للتصرف
استجابة 422 تحدد الحقل غير الصحيح. 401 تعني غياب المصادقة أو عدم صحتها، و403 تعني أن الهوية معروفة لكن العملية غير مسموحة. أحيانًا تكون 404 مناسبة حتى لا تكشف وجود سجل يخص شخصًا آخر. رموز الخطأ التي يعتمد عليها البرنامج يجب أن تبقى ثابتة حتى لو تُرجمت الرسالة للمستخدم.
استخدم معرف طلب لتتبع العملية بين الـ API والخدمات التي يستدعيها. بذلك يستطيع الدعم التحقيق دون صورة لاستثناء داخلي. تجنب تسجيل كلمات المرور وTokens وبيانات الدفع الكاملة.
قبل إصدار يكسر التوافق، اختبر نسخ الموبايل القديمة التي ما زالت مستخدمة. تحديث الويب سريع، أما تطبيق الموبايل فقد يبقى أشهرًا لدى المستخدمين. هذا يحدد فترة التوافق المطلوبة.
أصمم APIs للويب والموبايل بناءً على هذه المبادئ في خدمة Laravel Backend وتطوير الـ API.