هل يستحق الالتزام بـ«معايير» REST؟ المفاجأة التي حملتها لنا واجهة Apple البرمجية!
في معظم الأحيان لا يوجد معيار رسمي لتصميم واجهات REST البرمجية. وبعيدًا عن مواصفات HTTP، لا تجد سوى ممارسات جيدة يمكنك اعتمادها أو تجاهلها.
مقدمة
تُعدّ واجهات REST البرمجية على الأرجح أكثر آليات التواصل انتشارًا في واجهات الويب العامة. وكلما شرعت في التكامل مع خدمة تابعة لجهة خارجية، يمكنك أن تتوقع العمل مع REST. وفي بعض الحالات تحصل أيضًا على SDK أو تعريفات Open API تجعل استخدام الواجهة أكثر راحة؛ وفي حالات أخرى لا يكون بين يديك سوى التوثيق. سننظر اليوم في المعايير والتوقعات، وكذلك فيما قد تصادفه فعلًا في الواجهات الواقعية.
عملنا مؤخرًا على مشروع لأحد عملائنا. يتضمن تطبيقات جوّال تتكامل مع أنظمة دفع، منها Apple Wallet. فبعد إتمام عملية شراء، يتحقق الخادم الخلفي من المعاملة – قبل منح التراخيص أو العملات الافتراضية للألعاب – ليتأكد من أن المستخدم دفع فعلًا. بدأنا ببعض البحث ووجدنا وثائق Apple ذات الصلة، التي قادتنا إلى نقطة النهاية الصحيحة. لنتحدث عن كيفية تصميمها.
ملاحظة: لا نعرف المبررات وراء القرارات التقنية التي اتُّخذت عند تصميم هذه الواجهة. قد يكون السبب التوافق مع الإصدارات السابقة، أو الحاجة إلى التكامل مع أنظمة قديمة، أو عاملًا آخر لا يقل أهمية. وربما لم يكن المقصود أصلًا أن تكون REST، بل مجرد «واجهة HTTP» – كل ما يمكننا فعله هو التخمين. ومع ذلك، تجدر الإشارة إلى أن واجهات أخرى تتبع تصميمًا مختلفًا تمامًا.
نموذج نضج ريتشاردسون
في سياق هذا النقاش، يجدر ذكر نموذج نضج ريتشاردسون (Richardson Maturity Model)، الذي يقسّم نضج واجهات REST إلى أربعة مستويات. وهذا ملخص موجز جدًا:
- المستوى 0 – المستوى الأساسي لأي واجهة قائمة على الويب. قد تجد هنا مثلًا نقطة نهاية
POST /createProduct. - المستوى 1 – مسارات الواجهة تشير إلى موارد. يُتوقع أن تستخدم معرّفات URI أسماء بدل الأفعال، فترى مسارات مثل
/product/1بدل/createProduct. - المستوى 2 – تُستخدم أفعال HTTP بصورة أكثر توحيدًا – GET لجلب البيانات، وPOST/PUT للإنشاء، وهكذا. ولجلب منتج تستدعي
GET /product/1، ولإنشاء واحد تستدعيPOST /product. - المستوى 3 – HATEOAS (النص التشعبي كمحرّك لحالة التطبيق) – تحتوي الموارد التي تعيدها الواجهة على معرّفات URI تشير إلى موارد ذات صلة بدل المعرّفات المجردة. مثل هذه الواجهات نادرة جدًا، لأنها دون مساعدة مكتبات إضافية تميل إلى أن تكون معقدة التنفيذ. وفي مثالنا السابق، ستحتوي استجابة
GET /product/1على روابط لكل الكيانات ذات الصلة، ويمكنك اتباعها لاستكشاف مجموعة البيانات بأكملها.
في أغلب الأحيان، تكون الواجهات التي نصادفها من المستوى 2.
فعل HTTP ومسار نقطة النهاية
لنعد إلى نقطة نهاية Apple Verify Receipt. أول ما يلفت النظر هو نقطة النهاية نفسها: POST https://buy.itunes.apple.com/verifyReceipt (مع حساسية لحالة الأحرف!). مهمتها الرئيسية التحقق من بيانات الإيصال (سلسلة مشفّرة ترسلها تطبيقات الجوّال). هل كان يمكن تصميمها بطريقة أقرب إلى REST؟ لننظر. المسار لا يتعامل مع موارد (فهو يحتوي فعلًا)، ونرسل POST مع أنه لا يُنشأ شيء حقيقة. بل إنها تشبه المستوى 0.
كيف سيبدو التصميم البديل؟ الأمر ليس بسيطًا كما يبدو. لو بدأنا من الصفر، فقد يكون طلب GET مع معامل استعلام – GET لأن ما نفعله فعلًا هو استرجاع إيصال معاملة يحوي معلومات عن المنتج المشترى. لكن بيانات الإيصال المشفّرة القادمة من تطبيق الجوّال قد يتجاوز طولها 6000 محرف، بينما توصي بعض التوصيات بأن تبقى معاملات الاستعلام دون 2048. فما الخيارات الأخرى؟ إن مواصفات HTTP 1.1 لعام 2014 تسمح فعلًا بـGET مع جسم (body). لكن للأسف، المواصفات شيء والواقع شيء آخر: كثير من مكتبات عملاء REST لا تدعم ذلك أصلًا، فليس هذا خيارًا جيدًا أيضًا. هل من شيء آخر؟ يمكننا التفكير في POST ينشئ مورد verification – لكن مرة أخرى، على الأرجح لا يُنشأ شيء خلف الكواليس.
كيف يتعامل المنافسون مع ذلك؟ لننظر إلى Google Play API. نجد هنا
GET https://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/purchases/products/{productId}/tokens/{token}.
هذا أقرب بوضوح إلى REST. فالمعرّفان productId وtoken اللذان تمرّرهما سلسلتان أقصر بكثير من بيانات إيصال Apple. والسؤال الأساسي هو ما الذي تفعله نقطتا النهاية هاتان فعليًا خلف الكواليس – قد نخمّن أن Google تقرأ البيانات من قاعدة بيانات، بينما تفك Apple ببساطة ترميز البيانات المقدَّمة بمفتاح خاص. وإن كان الأمر كذلك، فلا يمكن إجراء مقارنة عادلة حقًا.
ومع أن بعض قرارات التصميم قد تكون مفاجئة، فمن المفيد أن نتذكر أن نمذجة REST أصعب مما تبدو. وأحيانًا لا توجد إجابة صحيحة واحدة تلبي كل الممارسات المثلى.
رموز الحالة
ما فاجأني حقًا في واجهة Apple هذه هي رموز الحالة. فنقطة النهاية التي بحثناها تعيد 200 OK في كل مرة. وتأتي الأخطاء في جسم الاستجابة كحقل حالة – القيمة 0 تعني صالحًا، وأي قيمة أخرى تدل على خطأ. فماذا يحدث إذا استدعيت GET على نقطة النهاية هذه بالخطأ؟ 200 OK، مع جسم يحتوي على الحالة 21000. وماذا لو أرسلت مدخلات غير صالحة (مثل مدخلات ليست JSON صالحًا)؟ 200 OK، مع جسم يحتوي على الحالة 21002. وفق مواصفات HTTP، يشير 200 OK إلى نجاح الطلب. يناقش الناس على الإنترنت ما إذا كان إرجاع 200 OK مع أخطاء منطق العمل في الجسم مقبولًا (فالطلب نفسه ينجح ويفشل المنطق فقط)، لكنني أرى أن هذا وضع مختلف تمامًا عن وضعنا هنا. فطريقة HTTP غير المسموح بها لا تستحق بوضوح 200 OK.
كيف يؤثر ذلك على العمل مع الواجهة؟ إنه بالتأكيد ليس ما يتوقعه المطوّر في البداية. فبعض عملاء REST ذوي الأنواع الصارمة يعاملون 200 OK على أنه نجاح ويحاولون تحويل الاستجابة إلى صيغة معيّنة. ويمكن بالطبع التعامل مع هذه الحالات، لكن ذلك يتطلب جهدًا أكبر قليلًا من المعتاد.
ملاحظة: لغة الاستعلام GraphQL تُقدَّم عبر HTTP أيضًا. وفيها من الشائع أن تُعاد الأخطاء بصيغة جسم محددة سلفًا مع الحالة
200 OK. ومع ذلك، وبحسب التنفيذ، قد تعود بعض الأخطاء برموز حالة أخرى. وكما ترى، يمكن استخدام HTTP بطرق مختلفة تمامًا بحسب بروتوكول التواصل و«المعايير» والممارسات.
اصطلاح تسمية JSON
أمر آخر جعلني أتساءل حقًا: لماذا؟ هكذا قد يبدو جسم الطلب:
{
“receipt-data”: “...”, …
}
وهذه هي الاستجابة:
{
“status”: 0,
“is_retryable: …,
…
}
هل لاحظت الفرق؟ تستخدم الطلبات kebab-case، بينما تستخدم الاستجابات snake_case. ومرة أخرى، يمكنك التعايش مع ذلك، لكن بعض مكتبات json تتوقع أن تتبع كائناتك نمط حالة أحرف واحدًا. ولا يوجد معيار لتسمية مفاتيح JSON – فبعض الشركات تعتمد snake_case (مثل GitHub أو Zalando)، وأخرى camelCase (مثل واجهات Apple الأخرى. وغالبًا ما يعود الاختيار إلى لغة البرمجة المستخدمة.
المصادقة
أمن الواجهات موضوع مهم دائمًا. هناك طرق كثيرة لمصادقة واجهات REST، وأشيعها تمرير المفاتيح في الترويسات (headers). وأحيانًا تمرّر الواجهات الأقدم المفاتيح في معاملات الاستعلام (غير مستحسن) أو في جسم الطلب – وهذا بالضبط ما يحدث هنا: يتضمن الجسم حقل كلمة مرور. مرة أخرى، ليس هذا الأسلوب الأكثر شيوعًا، لكنه أسلوب يمكننا قبوله. وهو يسبب مشكلات في الخادم الخلفي أكثر مما يسببها في جهة العميل، لأنه يجب فك ترميز جسم الطلب قبل أن تتم مصادقته. وفضلًا عن ذلك، إذا كنت تسعى إلى واجهات متسقة، فماذا تفعل مع نقطة نهاية GET التي يُفضَّل ألا يكون لها جسم (انظر القسم السابق عن أفعال HTTP)؟
الخلاصات
في معظم الأحيان لا يوجد معيار رسمي لتصميم واجهات REST البرمجية. وبعيدًا عن مواصفات HTTP، لا تجد سوى ممارسات جيدة يمكنك اعتمادها أو تجاهلها. وأرى أن الاتساق والتوثيق عالي الجودة يظلان أهم العوامل، لأنهما ببساطة يجعلان العمل مع الواجهة أسهل. وتحاول الشركات توثيق إرشاداتها، لكن كما تُظهر أمثلة Zalando أو Google Cloud أو GitHub، فقد تصبح هذه الإرشادات ضخمة! دعوني أكرر: واجهة REST ليست أسهل شيء في التصميم!
عند بناء واجهة، ضع مستخدميها في ذهنك. إن موارد مثل مواصفة Open API مفيدة للغاية – يمكنك استخدامها مع Postman أو لتوليد مكتبات عملاء للغات مختارة. كما أن بيئة تجريبية (sandbox) أو أمثلة طلبات تعمل مباشرة دون إعداد إضافات رائعة أيضًا وتسهّل العمل ببساطة.
يتميز تصميم واجهة التحقق من الإيصالات لدى Apple بأنه لافت للنظر وقد يكون مربكًا لمستخدميه. وكما ذكرنا سابقًا، لا نعرف أسباب هذا التصميم – ولا يسعنا إلا افتراض أنها كانت وجيهة.