عبدالله عبدالرحيم بن سنكر: قواعد تصميم REST API نظيف يريّح الطرفين

التطبيق يكلّم الخادم مئات المرات في اليوم، وكل هذا الكلام يمر من واجهة برمجية واحدة: الـ API. لما تكون مرتّبة، المطوّر الجديد يفهمها في ساعة، وتطبيق الجوال والموقع ولوحة التحكم يشتغلون عليها بدون مفاجآت. ولما تكون فوضى، كل شاشة جديدة تحتاج اجتماعاً. عبدالله عبدالرحيم بن سنكر بنى «يوجيسير UGCS» بتطبيقه لآيفون وأندرويد وخادمه الخلفي، وتطبيق بطرفين مثل هذا يكشف بسرعة قيمة الواجهة المرتبة. هذي القواعد اللي يلتزم فيها، في خمس مجموعات.

الروابط: أسماء موارد، مو أفعال

الرابط يصف الشي، وفعل HTTP يصف وش تسوي فيه. بدل /getOrders و /createOrder و /deleteOrder، عندك مورد واحد /orders، ومعه الأفعال: GET لقراءة القائمة، و POST لإنشاء طلب، و GET /orders/42 لطلب محدد، و PATCH لتعديل جزء منه، و DELETE لحذفه. والعلاقات تنكتب كتسلسل منطقي: /orders/42/items لعناصر الطلب. استخدم صيغة الجمع دائماً، وحروفاً صغيرة، وشرطة بين الكلمات، ولا تتجاوز مستويين من التداخل، لأن رابطاً مثل /customers/7/orders/42/items/3/notes يتعب كل من يقرأه. وانتبه لشي ثاني في الروابط: ما تحمل أسراراً. رمز الدخول مكانه ترويسة Authorization، مو معامل في الرابط، لأن الروابط تنحفظ في سجلات الخوادم وسجل المتصفح وأدوات المراقبة، وأي رمز فيها ممكن يتسرّب بدون ما يحس أحد. والاتصال كله عبر HTTPS بدون استثناء، حتى في نسخ الاختبار.

رموز الحالة: خلّ الخادم يقول الحقيقة

أكثر خطأ يتكرر: الخادم يرد 200 دائماً، ويحط داخل الرد «success: false». كذا كل مكتبة وأداة مراقبة تحسب الطلب ناجحاً، والتطبيق يضطر يفتح كل رد يدوّر فيه على الخبر. رموز HTTP موجودة عشان تُستخدم:

• 200 للقراءة والتعديل الناجح، و 201 لما ينشأ مورد جديد، و 204 لنجاح ما يرجع محتوى مثل الحذف.
• 400 لطلب شكله غلط، و 422 لبيانات شكلها سليم لكنها ما تعدّي قواعد التحقق، مثل بريد مسجّل من قبل.
• 401 لما المستخدم مو مسجّل أو انتهت جلسته، و 403 لما يكون مسجّلاً لكن ما عنده صلاحية. والخلط بينهم يربك التطبيق: الأول يعني «ودّه لشاشة الدخول»، والثاني يعني «اعرض له رسالة رفض».
• 404 لمورد مو موجود، و 409 لتعارض مثل موعد انحجز قبل ثوانٍ.
• 429 لما يتجاوز العميل حد الطلبات، و 500 لخطأ في الخادم نفسه، والأخير ما لازم يكشف تفاصيل داخلية للمستخدم.

الأخطاء: شكل واحد في كل مكان

لما يفشل طلب، المطوّر في الطرف الثاني يحتاج يعرف ثلاثة أشياء: وش صار، وليش، ووش يسوي. اتفق على شكل واحد للخطأ في كل الواجهة: رمز ثابت تقرأه الآلة مثل EMAIL_TAKEN، ورسالة يقرأها الإنسان، وتفاصيل الحقول اللي فيها مشكلة لو كانت أخطاء تحقق. وفيه معيار معروف لهذا اسمه Problem Details، تقدر تعتمده بدل ما تخترع شكلك الخاص. والرمز الثابت أهم من الرسالة: التطبيق العربي يترجم EMAIL_TAKEN لرسالة عربية مناسبة، بدل ما يعرض للمستخدم نصاً إنجليزياً جاي من الخادم. وأضف لكل رد معرّفاً فريداً للطلب، يظهر في الرد وفي سجلات الخادم معاً. لما يتصل عميل يقول «طلع لي خطأ»، وصوّر الشاشة وفيها المعرّف، تلقى سجل الطلب كاملاً في ثوانٍ بدل ما تدوّر بالوقت التقريبي واسم المستخدم.

القوائم والتواريخ والتكرار: تفاصيل تنكسر عند الكبر

• التقسيم لصفحات من أول يوم: لا ترجع كل الطلبات في رد واحد. والتقسيم بالمؤشر (cursor) أثبت من التقسيم بالإزاحة (offset) في القوائم اللي تتغير باستمرار، لأن إضافة عنصر جديد ما تخلّي المستخدم يشوف عنصراً مرتين.
• الفلترة والترتيب في معاملات الرابط، مثل /orders?status=paid&sort=-created_at، بدل نقطة نهاية جديدة لكل فلتر.
• التواريخ بصيغة ISO 8601 وبتوقيت UTC، والتطبيق يحوّلها لتوقيت المستخدم. تخزين «الساعة ٣» بدون منطقة زمنية قنبلة موقوتة.
• المبالغ بأصغر وحدة كعدد صحيح، يعني بالهللة بدل الريال بكسور عشرية، لأن الأعداد العشرية في البرمجة تطلّع فروقات تقريب صغيرة تتراكم.
• منع التكرار: تكرار GET و PUT و DELETE ما يغيّر النتيجة، لكن POST لا. لو ضغط المستخدم «ادفع» وانقطعت الشبكة وأعاد التطبيق المحاولة، ممكن ينشأ طلبان. الحل إن التطبيق يرسل معرّفاً فريداً مع الطلب في ترويسة مثل Idempotency-Key، والخادم ما ينفّذ نفس المعرّف مرتين.

الإصدارات والتوثيق: احترم اللي يستخدمون واجهتك

تطبيق الجوال يختلف عن الموقع في نقطة جوهرية: النسخة القديمة تبقى على أجهزة الناس شهوراً، لأن مو كل أحد يحدّث. لو غيّرت شكل رد في الخادم، ممكن تنكسر تطبيقات قديمة كثيرة في نفس اللحظة. عشان كذا: الإضافة آمنة، أما حذف حقل أو تغيير معناه فيحتاج إصداراً جديداً مثل /v2، ويبقى /v1 شغّالاً لين يتحدّث أغلب المستخدمين. ومن الجهة الثانية، تطبيق الجوال لازم يتجاهل أي حقل جديد ما يعرفه، بدل ما ينهار.

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

في منصة أزهل الرقمية تُكتب هذي القواعد قبل أول نقطة نهاية، مو بعد ما تتراكم الفوضى. والسبب عملي أكثر منه جمالي: الواجهة الخلفية تعيش أطول من أي شاشة، ويستخدمها ناس ما شافوا كودها. وعبدالله عبدالرحيم بن سنكر الكندي يختصرها بسؤال يسأله قبل أي قرار فيها: لو جاء مطوّر غريب بكرة، هل يقدر يستخدم هذي الواجهة بدون ما يتصل بي؟