رسائل الأخطاء المنظمة لواجهات برمجة التطبيقات HTTP
November 2, 2022
منذ أن بدأت العمل على مشروع Apache APISIX، كنت أحاول تحسين معرفتي وفهمي لـ REST RESTful واجهات برمجة التطبيقات (APIs) عبر HTTP. لهذا الغرض، أقوم بقراءة ومشاهدة المصادر التالية:
- الكتب. في الوقت الحالي، أنا على وشك الانتهاء من كتاب API Design Patterns. توقع مراجعة قريبًا.
- يوتيوب. أوصي بقناة ErikWilde. بينما بعض الفيديوهات أفضل من غيرها، إلا أنها جميعًا تركز على واجهات برمجة التطبيقات.
- IETF RFCs. معظم RFCs ليست عن واجهات برمجة التطبيقات، ولكن شخص ودود قام بتجميع قائمة بـ تلك التي تتعلق بها.
اليوم، أود أن أقدم RFC "تفاصيل المشكلة لواجهات برمجة التطبيقات عبر HTTP"، المعروف أيضًا باسم RFC 7807.
المشكلة (المشاكل)
تفرض مبادئ REST استخدام حالة HTTP للتواصل. بالنسبة للأخطاء، يعرّف HTTP نطاقين: أخطاء العميل، 4xx، وأخطاء الخادم، 5xx.
تخيل واجهة برمجة تطبيقات مصرفية تسمح لك بإجراء تحويلات. يجب أن تفشل إذا حاولت تحويل أموال أكثر مما لديك في حسابك. يمكن أن تناسبها بعض رموز حالة HTTP:
400 Bad Request: لا يمكن للخادم معالجة الطلب بسبب خطأ يُعتقد أنه من العميل.402 Payment Required: لا يمكن معالجة الطلب حتى يقوم العميل بالدفع. ومع ذلك، لا يوجد اتفاقية استخدام قياسية، وتستخدمها كيانات مختلفة في سياقات أخرى.409 Conflict: يتعارض الطلب مع الحالة الحالية للمورد المستهدف.
هنا تكمن المشكلة الأولى: تم تحديد رموز حالة HTTP للتفاعلات بين الإنسان والآلة عبر المتصفحات، وليس للتفاعلات بين الآلة والآلة عبر واجهات برمجة التطبيقات. وبالتالي، نادرًا ما يكون اختيار رمز حالة يتوافق بشكل مباشر مع حالة الاستخدام أمرًا بسيطًا. للتوضيح، يبدو أن مارتن فاولر يفضل 409 في حالتنا.
بغض النظر عن رمز الحالة، فإن المشكلة الثانية تتعلق بحمولة الخطأ، أو بشكل أدق، هيكلها. الهيكل ليس مهمًا إذا كانت منظمة واحدة تدير العميل وموفر واجهة برمجة التطبيقات. حتى إذا كان فريق مخصص يطور كل منهما، يمكنهما التنسيق. على سبيل المثال، تخيل تطبيقًا جوالًا يستدعي واجهة برمجة التطبيقات الخاصة به.
ومع ذلك، تظهر المشاكل عندما يقرر فريق استخدام واجهة برمجة تطبيقات تابعة لجهة خارجية. في هذه الحالة، يكون اختيار هيكل الاستجابة مهمًا لأنه يعتبر الآن جزءًا من عقد: أي تغيير من قبل الموفر قد يكسر العملاء. والأسوأ من ذلك، من المحتمل أن يكون الهيكل مختلفًا من موفر لآخر.
وبالتالي، فإن هيكل تقرير الأخطاء الموحد:
- يوفر التوحيد عبر الموفرين
- يزيد من استقرار واجهة برمجة التطبيقات
RFC 7807
RFC 7807 يهدف إلى حل المشكلة من خلال توفير هيكل موحد للأخطاء.
الهيكل هو التالي:
يصف RFC الحقول:
"type"(string) - مرجع URI [RFC3986] يحدد نوع المشكلة. تشجع هذه المواصفات على أن يوفر، عند الإشارة إليه، وثائق قابلة للقراءة البشرية لنوع المشكلة (مثل، باستخدام HTML [W3C.REC-html5-20141028]). عندما لا يكون هذا العضو موجودًا، يُفترض أن تكون قيمته"about:blank"."title"(string) - ملخص قصير وقابل للقراءة البشرية لنوع المشكلة. يجب ألا يتغير من حدوث إلى آخر للمشكلة، إلا لأغراض الترجمة (مثل، باستخدام التفاوض الاستباقي للمحتوى؛ انظر [RFC7231, Section 3.4])."status"(number) - الحالة ([RFC7231], Section 6) التي تم إنشاؤها بواسطة الخادم الأصلي لهذا الحدث من المشكلة."detail"(string) - شرح قابل للقراءة البشرية خاص بهذا الحدث من المشكلة."instance"(string) - مرجع URI يحدد الحدث المحدد للمشكلة. قد يوفر أو لا يوفر معلومات إضافية عند الإشارة إليه.
يقدم RFC العينة التالية عندما لا توجد أموال كافية لإجراء تحويل مصرفي.
مثال
سأستخدم أحد العروض التوضيحية الخاصة بي كمثال. يسلط العرض التوضيحي الضوء على عدة خطوات لتسهيل عملية تطوير واجهات برمجة التطبيقات الخاصة بك.
في الخطوة 6، أريد أن يقوم المستخدمون بالتسجيل، لذلك أقوم بتحديد عدد المكالمات في نافذة زمنية إذا لم يتم التحقق من هويتهم. لقد قمت بإنشاء مكون إضافي مخصص لـ Apache APISIX لهذا الغرض. بعد وصول عدد المكالمات إلى الحد المسموح، يعود بـ:
HTTP/1.1 429 Too Many Requests
Date: Fri, 28 Oct 2022 11:56:11 GMT
Content-Type: text/plain; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Server: APISIX/2.15.0
{"error_msg":"Please register at https:\/\/apisix.org\/register to get your API token and enjoy unlimited calls"}
لنقم بتنظيم الرسالة وفقًا لـ RFC 7807.
الخاتمة
RFC 7807 لا يساعد فقط مطوري العملاء. إنه مساعدة كبيرة لمطوري واجهات برمجة التطبيقات حيث يوفر إرشادات سريعة لتجنب إعادة اختراع العجلة في كل مشروع.
المزيد:
نُشرت أصلاً على A Java Geek في 30 أكتوبر 2022