تصميم واجهات API

أصعب ما في الأمر أن الواجهة لا يمكن إعادة هيكلتها بهدوء. الكود الداخلي يمكن إعادة تشكيله متى شئت؛ أما الواجهة العامة فلها مستهلكون لا تتحكم بجدول إصداراتهم، وبعضهم لن يُحدّث أبداً. وهذا يجعل الشكل الأولي مكلفاً بشكل غير معتاد إن أخطأت فيه، ويجعل إدارة الإصدارات أمراً تصممه من البداية لا تخترعه عند أول تغيير كاسر. والتطوير بالإضافة — حقول اختيارية جديدة، ونقاط نهاية جديدة، ولا حذف — يشتري لك سنوات قبل الحاجة إلى إصدار ثانٍ.

السؤال عن REST أم GraphQL يُطرح أكثر مما يهمّ. GraphQL يستحق تعقيده حين تحتاج عملاء كثيرون مختلفون مجموعات جزئية مختلفة الشكل من رسم بياني غني، وهو يجلب كلفاً حقيقية: تحليل كلفة الاستعلام، وتخزين مؤقت لم يعد مجانياً من HTTP، ومخطط يصبح مشكلة حوكمة بذاته. أما لعدد قليل من العملاء يستهلكون موارد متوقعة، فإن REST بنقاط نهاية مختارة جيداً أبسط في البناء والتخزين والتصحيح والشرح — والبساطة في واجهة يعتمد عليها آخرون ميزة.

وما تبقّى تشغيلي ويُؤجَّل حتى يؤلم. حدود المعدل تحميك من أن تُسقط حلقة إعادة محاولة لعميل واحد الخدمة على الجميع، ويجب إبلاغها في الترويسات لا اكتشافها عبر الإخفاقات. ومفاتيح عدم التكرار تتيح للعميل إعادة المحاولة بأمان بعد انتهاء المهلة دون إنشاء عملية خصم ثانية. والأخطاء يجب أن تكون مقروءة آلياً ومحددة، لأن "400 Bad Request" بلا تفصيل يحوّل كل تكامل إلى محادثة دعم.