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