- الاتساق أهم من الأناقة — نمط واحد مطبق بانضباط.
- رسائل الخطأ يجب أن تخبر ما الخطأ وكيف يصلح.
- خطط للإصدارات من اليوم الأول لا عند أول تغيير كاسر.
- التوثيق جزء من المنتج لا ملحق يكتب لاحقا.
الاتساق قبل كل شيء
المستهلك يتعلم نمطك من أول ثلاث نقاط نهاية ثم يفترض بقيتها. فإن سميت جمعا هنا ومفردا هناك، وأعدت كائنا في موضع ومصفوفة في آخر، أجبرته على قراءة التوثيق لكل نداء. والاتساق يوفر عليه وعليك أكثر من أي تحسين آخر.
- أسماء الموارد بالجمع دائما، وبنمط تسمية واحد.
- شكل استجابة موحد: غلاف واحد للبيانات وللأخطاء.
- صيغة تواريخ واحدة معيارية بمنطقة زمنية صريحة.
- نمط ترقيم واحد لكل القوائم بلا استثناءات.
الأخطاء: أهم ما يهمل
رمز الحالة وحده لا يكفي. والخطأ الجيد يحمل ثلاثة أشياء: رمزا ثابتا يمكن للكود التعامل معه، ورسالة يقرأها المطور تشرح السبب، وإشارة إلى الحقل المعني إن كان خطأ تحقق. أما رسالة حدث خطأ فتحول التصحيح إلى تخمين.
ولا تسرب في رسائل الخطأ تفاصيل داخلية: مسارات الملفات، وأسماء الجداول، وآثار التتبع. فهذه مادة للمهاجم لا للمطور.
الإصدارات والتغيير
- ضع رقم الإصدار في المسار من أول يوم — إضافته لاحقا أصعب.
- الإضافة غير كاسرة: حقل جديد لا يكسر مستهلكا يتجاهله.
- الحذف وتغيير المعنى كاسران دائما ويحتاجان إصدارا جديدا.
- أعلن الإهمال مبكرا وأعط مهلة معقولة قبل الإيقاف.
الترقيم والحدود
كل نقطة نهاية تعيد قائمة يجب أن ترقم افتراضيا بحد أقصى معقول. فالقائمة التي تعيد كل شيء تعمل في التطوير بعشرة سجلات وتسقط في الإنتاج بمليون. وضع حدا لعدد الطلبات أيضا لكل مستهلك، وأعلمه بحدوده في الترويسات.
التوثيق
التوثيق المولد من التعريف يبقى متزامنا مع الكود بخلاف المكتوب يدويا. وأضف إليه ما لا يولد آليا: أمثلة نداء واستجابة حقيقية، ووصف حالات الخطأ، وسيناريو كامل لأشيع مهمة يريدها المستهلك.
أسئلة شائعة
هل نستعمل REST أم GraphQL؟
REST أبسط وأوسع دعما ويكفي أغلب الحالات. وGraphQL يبرر نفسه حين يكون للمستهلكين احتياجات بيانات شديدة التنوع وتصبح النقاط المخصصة عبئا. والاختيار على أساس نمط الاستهلاك لا الحداثة.
كيف نؤمن الواجهة؟
مصادقة معيارية بمفاتيح أو رموز محدودة الصلاحية والمدة، وتحقق من الصلاحية لكل نداء لا عند الدخول فقط، وتشفير النقل، وحد لعدد الطلبات، وتسجيل كامل. وخصوصا: لا تعتمد على إخفاء نقطة النهاية كإجراء أمني.
متى نكسر التوافق؟
حين لا يوجد بديل، وبإصدار جديد يعمل بالتوازي مع القديم مدة كافية. والكسر المفاجئ يوقف أنظمة عملاء ويكلف ثقة يصعب استعادتها.
- تصميم API
- واجهات برمجية
- REST
- تكامل الأنظمة
- توثيق الواجهات
- إصدارات API
- هندسة البرمجيات
- تطوير البرمجيات والتطبيقات