حافظ على بساطة واجهتك البرمجية: الطريق إلى الكفاءة وسهولة الاستخدام
واجهة API هي نقطة الدخول إلى أي أداة، لذا فإن ضبط تعقيدها أمر مهم. وحين يعتمد عملك على خدمات API، قد تصبح البساطة ميزة تنافسية.
عند اختيار أداة، ينبغي أن نوازن بين كلفتها ومدى تلبيتها لاحتياجاتنا. يجب أن تؤدي العمل الذي نتوقعه منها وأن تؤديه جيدًا. وأحيانًا، إذا كانت أداتان بالقدر نفسه من القدرة، فإن الأبسط هي الخيار الأفضل لأنها توفّر الوقت. وواجهة API هي نقطة الدخول إلى الأداة، لذا فإن ضبط تعقيدها أمر مهم. وحين يعتمد عملك على خدمات API، قد تصبح البساطة ميزة تنافسية.
يناقش هذا المقال كيف يقود التعقيد إلى المشكلات في واجهات API. سنفحص ما الذي قد يجعل API أكثر تعقيدًا، بما في ذلك ما يجب أن تؤديه وكيف صُمّمت. وستساعدك قراءته على:
- تجنّب التعقيد غير الضروري.
- تحديد مصادر التعقيد.
- تبسيط الحلول القائمة وجعلها أكثر كفاءة.
ما هو التعقيد (Complication)
أولًا، علينا أن نحدد ما الذي تعنيه كلمة complication فعلًا. يعرّف القاموس complication بأنها:
شيء يجعل الموقف أصعب، أو فعل جعله كذلك
وفي حالة واجهات API يشمل ذلك كل ما يجعل استخدام API أو بناءها أصعب.
وتجدر الإشارة إلى أن «complication» و«complexity» تُعامَلان كثيرًا كمترادفتين، مع أن معنييهما يختلفان قليلًا. وعند البحث عن complexity في القاموس نجد أنها تشير إلى:
حالة التكوّن من أجزاء كثيرة وصعوبة الفهم أو الحل
وفي واجهات API قد يتعلق التعقيد بالبنية (مثل عدد نقاط النهاية والترويسات والسمات في جسم الرسالة) أو بالنظام المخفي خلف API (مثل عدد الوحدات أو الخدمات المصغّرة). والتعقيد بلا شك أحد الأمور التي قد تؤدي إلى الـ complication.
وبسبب هذا الفرق، سيتحدث بقية المقال في الغالب عن «complication» وليس «complexity». وقد اخترت هذا المصطلح لأؤكد على التحديات والصعوبات المحددة التي قد تنشأ عند تصميم واجهات API واستخدامها.
مشكلات الـ API المفرط التعقيد
يمكن أن تنشأ مشكلات كثيرة عن التعقيد في API. وأكثرها شيوعًا:
| من وجهة نظر مَن يدمج API | من وجهة نظر مزوّد API |
| فشل التكاملات كثيرًا | الاختبار مرهق |
| وقت طويل يُقضى في تصفّح التوثيق | المراقبة صعبة |
| حجم كبير من الطلبات إلى فريق دعم API | التوسّع صعب |
| تستغرق التكاملات وقتًا طويلًا | وقت كبير يذهب في معالجة طلبات المدمِجين |
| الصيانة تتطلب جهدًا كبيرًا | تستغرق الميزات الجديدة وقتًا طويلًا حتى تُسلَّم |
| الصيانة تتطلب جهدًا كبيرًا |
عندما تلاحظ أيًّا من هذه الأعراض، من الضروري أن تعرف ما وراءها وأن تتحقق مما إذا كانت ناتجة عن تعقيد API. وإذا كانت كذلك، فخذ لحظة للتفكير في كيف أصبح API بهذا الالتواء. فهذا التأمل هو مفتاح إزالة السبب الجذري للمشكلة أو على الأقل الحد من أثرها بفعالية.
تتناول الأقسام التالية العوامل التي تؤثر في تعقيد API.
عوامل تعقيد API
هناك أشياء كثيرة جدًا قد تجعل API معقدًا بحيث يكاد يستحيل سردها ووصفها كلها في مقال واحد. لكن جميعها تقريبًا تقع ضمن إحدى هذه المجموعات:
- المتطلبات الوظيفية: كل ما هو متوقع من حيث الوظائف المقدَّمة.
- المتطلبات غير الوظيفية: كل ما هو متوقع من حيث الأداء والموثوقية والأمان وسمات الجودة الأخرى.
- ضعف بنية API: تصميم وترتيب غير مثاليين لمكونات API ونقاط نهايته وتفاعلاته.
بعد ذلك سنستعرض كل مجموعة من هذه المجموعات، مع إبراز تحدياتها الخاصة والاعتبارات المصاحبة لها.
الوظائف التي يوفرها API
يوجد API أساسًا لكشف الوظائف التي يمكن للمدمجين استخدامها. لكن مع إضافة المزيد من الميزات قد يزداد API تعقيدًا. ولهذا فإن اختيار الوظائف التي تدخل في API يستحق عناية حقيقية. وعادةً يحكم القرار ما يطلبه العملاء أكثر من غيره، لكن يمكن أيضًا مراعاة جوانب أخرى، مثل مدى انسجام الميزة مع استراتيجية العمل لدى مزوّد API.
ولتوضيح ذلك، لنأخذ API لمكتبة بيع كتب مثالًا. هنا نكشف نقطة نهاية تعيد الكتب المتاحة مع الأسعار بعملة يختارها عميل API عبر معامل الاستعلام هذا:
GET /book-store-api/books?price.currency=USD
{
"books": [
{
"id": "04b1d68-3a85-4ec0-a4e6-8d7a936d4c02",
"title": "Clean Code: A Handbook of Agile Software Craftsmanship",
"author": "Robert C. Martin",
"stock": 3,
"price": {
"amount": 15,
"currency": "USD"
},
"description": "Unlock the secrets to writing pristine,
maintainable, and efficient code that stands the test of time.
Discover essential principles, patterns, and best
practices that empower you to create software that is
not only functional but also a joy to read and work with.
Take your programming skills to the next level
with this indispensable guide to achieving clarity,
simplicity, and excellence in your code."
},
{
"id": "9d2bf831-7fe4-4fb3-ba8c-aa724ac5a773",
"title": "The Pragmatic Programmer: Your journey to mastery",
"author": "David Thomas, Andrew Hunt",
"stock": 5,
"price": {
"amount": 17,
"currency": "USD"
},
"description": "Your essential guide to mastering
the art of pragmatic software development. Learn how
to approach coding challenges with a practical
mindset, leverage powerful tools, and adopt
efficient techniques that lead to success in
any programming project. Unravel the secrets
of effective team collaboration, debugging,
and problem-solving to become a highly
skilled and adaptable developer. Packed
with timeless wisdom and real-world advice,
this book is your roadmap to becoming
a truly pragmatic programmer."
}
]
}
إن السماح للعميل باختيار عملة السعر يضيف تعقيدًا هنا ويجلب التحديات التالية:
- تقلب العملات: بما أن أسعار الكتب تعتمد على أسعار الصرف، فقد تكون غير مستقرة، مما قد يعني أن يرى العملاء أسعارًا غير متسقة.
- تعقيد سياسة الاسترجاع: قد تصبح سياسة استرجاع المشتريات بعملات مختلفة معقدة، لأن المبلغ المسترجع قد يتغير مع أسعار الصرف.
- آلية أسعار الصرف: يجب أن يوجد ما يجلب أسعار الصرف ويديرها حتى تكون تحويلات العملات صحيحة.
- معالجة الأعطال: يجب التعامل بسلاسة مع أخطاء جلب أسعار الصرف حتى لا تتعطل الخدمة.
يمكن التعامل مع كل هذه التحديات، لكن من المهم التفكير بعناية فيما إذا كانت القيمة التجارية لتوفير API بعدة عملات تبرر التكاليف والصعوبات المذكورة أعلاه.
الدرس هنا هو الحذر عند تحديد الميزات التي سنبنيها. فكل وظيفة جديدة لها ثمن، وغالبًا ما يتجاوز هذا الثمن كلفة تنفيذها. ويلزم تفكير متأنٍّ لإيجاد التوازن الصحيح بين تقديم القيمة وإبقاء تعقيد API تحت السيطرة.
المتطلبات غير الوظيفية
تتعلق المتطلبات غير الوظيفية بالخصائص العامة للنظام التي لا ترتبط مباشرة بمجال معين. ففي كتاب “Fundamentals of Software Architecture” لمارك ريتشاردز ونيل فورد تُسمّى خصائص العمارة (Architecture Characteristics) وتوصف هكذا:
الجوانب المهمة في النظام التي لا تعتمد على مجال المشكلة
ويشدد المؤلفان أيضًا على أن هذه المتطلبات ينبغي إبقاؤها في الحد الأدنى بدلًا من تكديسها:
يمكن لأي تطبيق أن يوفر عددًا هائلًا من خصائص العمارة – لكن لا ينبغي له ذلك. فكل خاصية عمارة يدعمها تجعل التصميم أكثر تعقيدًا. ولهذا فإن من المسؤوليات الأساسية للمعماري أن يختار أقل عدد ممكن من خصائص العمارة، لا أكبر عدد ممكن منها.
وأنا أتفق تمامًا مع هذا الرأي. فكل متطلب غير وظيفي قد يجعل API أكثر تعقيدًا. وفيما يلي سنتناول عدة متطلبات غير وظيفية – إمكانية الوصول والموثوقية والأداء والتوافق مع الإصدارات السابقة وقابلية النقل والأمان – ونحلل كيف يمكن لكل منها أن يعقّد API.
إمكانية الوصول (Accessibility)
تعني إمكانية الوصول تصميم المنتجات أو الخدمات أو المحتوى الرقمي بحيث يستطيع أكبر عدد ممكن من الناس الوصول إليها واستخدامها. لننظر كيف يمكن أن تجعل إضافة التدويل (internationalization) واجهة API أكثر تشابكًا.
لنأخذ API المكتبة السابق. للتعامل مع لغات متعددة، يمكن اختيار اللغة عبر ترويسة Language، هكذا:
الاستجابة بالإنجليزية:
GET /book-store-api/books?price.currency=USD
-h Language:en
{
"books": [
{
"id":"04b1d68-3a85-4ec0-a4e6-8d7a936d4c02",
"title": "Clean Code: A Handbook of Agile Software Craftsmanship",
"author": "Robert C. Martin",
"stock": 3,
"price": {
"amount": 15,
"currency": "USD"
},
"description": "Unlock the secrets
to writing pristine, maintainable,
and efficient code that stands the
test of time. Discover essential principles,
patterns, and best practices that
empower you to create software
that is not only functional but also
a joy to read and work with. Take
your programming skills to the next
level with this indispensable guide to
achieving clarity, simplicity, and
excellence in your code."
},
{
"id":"9d2bf831-7fe4-4fb3-ba8c-aa724ac5a773",
"title": "The Pragmatic Programmer: Your journey to mastery",
"author": "David Thomas, Andrew Hunt",
"stock": 5,
"price": {
"amount": 17,
"currency": "USD"
},
"description": "Your essential guide to
mastering the art of pragmatic software
development. Learn how to approach
coding challenges with a practical mindset,
leverage powerful tools, and adopt efficient
techniques that lead to success in any
programming project. Unravel the secrets
of effective team collaboration, debugging,
and problem-solving to become a highly
skilled and adaptable developer. Packed
with timeless wisdom and real-world advice,
this book is your roadmap to becoming
a truly pragmatic programmer."
}
]
}
قد يبدو التدويل تعقيدًا بسيطًا، لكنه يجلب تحديات. فبالنسبة إلى المدمِج قد يبدو مجرد ترويسة إضافية لاختيار اللغة. أما لمطوري API فإن بناء الآلية يتطلب تفكيرًا متأنيًا. ويتعلق أحد أهم تبعات التدويل بالصيانة مستقبلًا: فأي محتوى جديد يعيده API ويعتمد على اللغة يجب ترجمته إلى كل لغة مدعومة. يمكن أتمتة الترجمة، لكن المترجمين البشريين لازمون لضمان الجودة، ما يعني تكاليف إضافية على الشركة التي تطوّر API. وقد يبطئ ذلك أيضًا تطوير API – فمهمة بسيطة تستغرق يومًا قد تمتد إلى أسبوع في انتظار الترجمات.
ولهذا ينبغي اختيار اللغات المدعومة بعناية وحصرها في الأهم منها من منظور المنتج. قد تبدو إضافة لغة أخرى سهلة أثناء التطوير، لكنها على المدى الطويل قد تحمل تكاليف صيانة مرتفعة.
المسؤولية (Liability)
في العمارة البرمجية تعني المسؤولية أن نظامًا أو مكوّنًا ما مسؤول أو مساءَل عن سلوكيات أو وظائف أو نتائج معينة. وهي إحدى خصائص العمارة التي تهدف إلى تحديد من يملك ماذا وما الالتزامات التي يحملها كل جزء من تصميم النظام. وفي واجهات API قد ترتبط المسؤولية بالوفاء بمتطلبات ناشئة عن التزامات قانونية وشهادات ومواصفات API.
ولتوضيح المشكلة بصورة أكبر، لنعد إلى API المكتبة ونتأمل السيناريو التالي:
تريد المكتبة توسيع خيارات الدفع بإضافة وسائل دفع جديدة، مثل العملات المشفرة (مثل Bitcoin و Ethereum) والمحافظ الرقمية (مثل Apple Pay و Google Pay).
هنا قد تُلزم وسائل الدفع الجديدة API بالامتثال لأنظمة واعتبارات مثل:
- أنظمة العملات المشفرة: بما أن العملات المشفرة تعمل على شبكات لامركزية، فقد يخضع استخدامها في المعاملات المالية لأنظمة محددة. وسيتعين على API الامتثال لقواعد العملات المشفرة المعمول بها، بما في ذلك متطلبات مكافحة غسل الأموال (AML) واعرف عميلك (KYC).
- أنظمة المحافظ الرقمية: مع المحافظ الرقمية قد يتعين على API اتباع القواعد التي يضعها كل مزوّد محفظة والتعامل مع بيانات العملاء – مثل بيانات الدفع والمعلومات الشخصية – بأمان. وفوق ذلك يأتي Apple Pay و Google Wallet بإجراءات استرجاع خاصة بهما، يجب التعامل معها بعناية وصحة.
- قوانين حماية البيانات والخصوصية: بمجرد إضافة وسائل دفع جديدة، يتعين على API معالجة أي مسائل حماية بيانات وخصوصية مرتبطة بمعالجة معلومات مالية وشخصية إضافية.
- معايير الأمان المالي: يجب أن يتبع API ممارسات الأمان المعتمدة في القطاع لحماية بيانات الدفع الحساسة ومنع الاحتيال أو الوصول غير المصرح به.
- موافقة المستخدم والاتفاقيات: بحسب وسيلة الدفع، قد يتعين على API الحصول على موافقة صريحة من المستخدمين لمعالجة المدفوعات بخيارات معينة واحترام أي اتفاقيات أو شروط خدمة مرتبطة بتلك الوسائل.
عند إضافة وسائل دفع جديدة إلى API المكتبة، على المؤسسة أن تقيّم هذه الالتزامات القانونية الجديدة وتفي بها بعناية. وقد يعني ذلك تحديث وظائف API وبروتوكولات الأمان ومعالجة المدفوعات لتلبية الأنظمة المنطبقة على وسائل الدفع المختارة. وإلى جانب تكاليف تطوير هذه الآليات، قد يتطلب الأمر توظيف مختصين قانونيين لضمان الامتثال الكامل.
الأداء (Performance)
يبرز جانبان رئيسيان عند الحديث عن أداء API: زمن الاستجابة الذي يقيس المدة التي تستغرقها معالجة طلب واحد، والإنتاجية (throughput) التي تقيس عدد الطلبات التي يستطيع API معالجتها في وحدة زمنية معينة. ويمكن تحسين الأداء بآليات متنوعة، منها مثلًا الترقيم (pagination) الذي يسترجع مجموعات البيانات الكبيرة ويعرضها بكفاءة، والتخزين المؤقت من جهة الخادم الذي يبقي البيانات كثيرة الطلب في متناول اليد ويقلل المعالجة المتكررة. وبفضل هذه التحسينات يمكن لـ API أن يستجيب أسرع ويخدم طلبات أكثر ويمنح المستخدمين تجربة أكثر سلاسة وتجاوبًا.
وفي الوقت نفسه قد تجعل هذه الآليات API أكثر تعقيدًا. لنرَ كيف يمكن أن تعقّد إضافة التخزين المؤقت من جهة الخادم API المكتبة. إن نقطة النهاية المعروضة سابقًا، التي تعيد الكتب المتاحة، مرشحة جيدة للتخزين المؤقت العكسي – خاصة عندما تتغير قائمة الكتب والمخزون والأسعار وأسعار الصرف نادرًا:
التخزين المؤقت من جهة الخادم المنفَّذ بشكل صحيح ينبغي أن يكون غير مرئي للعميل. أما إذا نُفِّذ بشكل سيئ فقد يحصل العميل على استجابات قديمة، أو قد يضر التخزين المؤقت نفسه بأداء API. ولمنع ذلك، على مزوّدي API التفكير بعناية في التحديات والمزالق المحتملة، مثل:
- إبطال التخزين المؤقت (Cache Invalidation): التأكد من تحديث التخزين المؤقت أو إبطاله فورًا عند تغير البيانات الأصلية، حتى لا يحصل العملاء على معلومات قديمة أو خاطئة.
- سياسات انتهاء الصلاحية: وضع سياسات انتهاء صلاحية مناسبة توازن بين حداثة البيانات وكفاءة التخزين المؤقت، بحيث لا تعيش البيانات المخزنة وقتًا أطول أو أقصر مما يلزم.
- اتساق البيانات: إبقاء البيانات المخزنة مؤقتًا متسقة مع مصدر الواجهة الخلفية لتجنب التناقضات وعدم تطابق البيانات.
- حجم التخزين المؤقت وإدارة الذاكرة: التحكم في حجم التخزين المؤقت واستخدام الذاكرة لتجنب الاستهلاك المفرط للموارد والحفاظ على قابلية النظام للتوسع.
- الأثر على الأداء: اختبار آلية التخزين المؤقت بدقة لقياس أثرها على أداء API وتجنب خلق اختناقات أداء جديدة.
- اعتبارات الأمان: معالجة مخاطر الأمان في تخزين البيانات الحساسة مؤقتًا بالتأكد من عدم حفظ المعلومات الحساسة في التخزين المؤقت وضبط ضوابط الوصول بشكل سليم.
يتطلب قرار إضافة آلية تخزين مؤقت تفكيرًا متأنيًا، لذا يجدر بك التفكير مرتين قبل المضي قدمًا.
التوافق مع الإصدارات السابقة (Backward compatibility)
يتوقع الجميع تقريبًا أن تكون واجهات API متوافقة مع الإصدارات السابقة، لكن هناك عدة طرق لتحقيق ذلك، وغالبًا ما تتضمن إصدار API (versioning) بإحدى صوره العديدة. وللقرارات المتعلقة بالتوافق مع الإصدارات السابقة أثر كبير في تعقيد API، ما يجعله موضوعًا كبيرًا – سبق أن تناولته بتعمق أكبر في مقال منفصل:
- Breaking Changes in APIs: يتناول هذا المقال خيارات تقلل من تكرار التغييرات الكاسرة أو تزيلها كليًا، مما يسهّل الانتقال على مستهلكي API.
وحتى مع السعي إلى التوافق مع الإصدارات السابقة، يبقى من الضروري اتخاذ قرارات مدروسة تناسب حالة استخدام API المعينة على أفضل وجه.
قابلية النقل (Portability)
قابلية نقل API خاصية مهمة تتيح نقل API واستخدامه على منصات وأنظمة مختلفة دون تغييرات كبيرة. ودعم عدة صيغ بيانات جزء كبير من قابلية النقل، إذ يتيح لـ API خدمة نطاق أوسع من العملاء. لكن لاحظ أن دعم صيغ متعددة قد يجعل API أكثر تعقيدًا أيضًا.
كمثال، لنأخذ API المكتبة ولنفترض أننا نريد دعم صيغتي JSON و XML باستخدام آليات التفاوض على المحتوى (content negotiation).
استجابة نقطة نهاية الكتب بصيغة JSON
GET /book-store-api/books?price.currency=USD
-h Accept:application/json
{
"books": [
{
"id":"04b1d68-3a85-4ec0-a4e6-8d7a936d4c02",
"title": "Clean Code: A Handbook of Agile Software Craftsmanship",
"author": "Robert C. Martin",
"stock": 3,
"price": {
"amount": 15,
"currency": "USD"
},
"description": "Unlock the secrets to writing
pristine, maintainable, and efficient code
that stands the test of time. Discover
essential principles, patterns, and best
practices that empower you to create
software that is not only functional but
also a joy to read and work with. Take
your programming skills to the next
level with this indispensable guide
to achieving clarity, simplicity, and
excellence in your code."
},
{
"id":"9d2bf831-7fe4-4fb3-ba8c-aa724ac5a773",
"title": "The Pragmatic Programmer: Your journey to mastery",
"author": "David Thomas, Andrew Hunt",
"stock": 5,
"price": {
"amount": 17,
"currency": "USD"
},
"description": "Your essential guide
to mastering the art of pragmatic
software development. Learn how
to approach coding challenges with
a practical mindset, leverage powerful
tools and adopt efficient techniques
that lead to success in any programming
project. Unravel the secrets of effective
team collaboration, debugging, and
problem-solving to become a highly
skilled and adaptable developer. Packed
with timeless wisdom and real-world
advice, this book is your roadmap to
becoming a truly pragmatic programmer."
}
]
}
استجابة نقطة نهاية الكتب بصيغة XML:
GET /book-store-api/books?price.currency=USD
-h Accept:application/xml
<?xml version="1.0" encoding="UTF-8" ?>
<root>
<books>
<id>04b1d68-3a85-4ec0-a4e6-8d7a936d4c02</id>
<title>Clean Code: A Handbook of Agile Software Craftsmanship</title>
<author>Robert C. Martin</author>
<stock>3</stock>
<price>
<amount>15</amount>
<currency>USD</currency>
</price>
<description>Unlock the secrets to
writing pristine, maintainable, and
efficient code that stands the test of
time. Discover essential principles,
patterns, and best practices that
empower you to create software that
is not only functional but also a joy
to read and work with. Take your
programming skills to the next level
with this indispensable guide to achieving
clarity, simplicity, and excellence
in your code.
</description>
</books>
<books>
<id>9d2bf831-7fe4-4fb3-ba8c-aa724ac5a773</id>
<title>The Pragmatic Programmer: Your journey to mastery</title>
<author>David Thomas, Andrew Hunt</author>
<stock>5</stock>
<price>
<amount>17</amount>
<currency>USD</currency>
</price>
<description>Your essential guide
to mastering the art of pragmatic
software development. Learn how
to approach coding challenges
with a practical mindset, leverage
powerful tools, and adopt efficient
techniques that lead to success
in any programming project.
Unravel the secrets of effective
team collaboration, debugging,
and problem-solving to become
a highly skilled and adaptable
developer. Packed with timeless
wisdom and real-world advice,
this book is your roadmap to
becoming a truly pragmatic programmer.
</description>
</books>
</root>
يمكن أن يجلب دعم عدة صيغ عددًا من التحديات:
- يجب على مدمجي API تحديد نوع المحتوى الذي يريدون استلام البيانات به؛ وإن لم يفعلوا فسيحصلون على الصيغة الافتراضية، شرط أن تكون مضبوطة.
- يحتاج العملاء إلى توثيق جيد يشرح كيفية استخدام الصيغ المختلفة والتعامل معها بشكل صحيح.
- يجب تطبيق كل تغيير في API على جميع الصيغ المدعومة للحفاظ على اتساقها وتجنب التباينات.
وكما سبق، يجدر التساؤل عما إذا كان تحقيق متطلب قابلية النقل يقدّم قيمة تجارية كافية لتعويض الزيادة المحتملة في التعقيد.
الأمان (Security)
الأمان شرط لا غنى عنه لواجهات API على الويب. فهو يحدد القواعد التي يجوز للعملاء بموجبها الوصول إلى أجزاء API المختلفة، بما في ذلك شروط مثل مستوى الوصول الممنوح ومعدل إرسال العميل للطلبات. ويحمي هذا الجانب الأساسي موارد API ويتحكم في كيفية استخدامها، مما يجعل التفاعل بين العملاء ووظائف API آمنًا ومنظمًا.
من أكثر طرق ترخيص العملاء شيوعًا استخدام JWT (JSON Web Token) مع آليات مثل OAuth 2.0. يوفر JWT طريقة مدمجة ومكتفية ذاتيًا لتمرير معلومات التفويض بين الأطراف، مما يجعله خيارًا شائعًا لتأمين تفاعلات API. أما OAuth 2.0 فيقدّم إطار تفويض موحّدًا يتيح تفويض حقوق الوصول إلى العملاء بأمان دون كشف بيانات الاعتماد الحساسة. وعند الجمع بينهما توفر هاتان التقنيتان أساسًا متينًا لحماية موارد API مع تسهيل منح وصول مضبوط للعملاء المصرح لهم.
ومع ذلك، يأتي تنفيذ JWT و OAuth 2.0 بمجموعة من التحديات والاعتبارات التي يجب التعامل معها بعناية للحفاظ على فعالية الأمان وسلامته، مثل:
- صلاحية الرمز وانتهاؤها (Token Validity and Expiry): إدارة أعمار الرموز وتجديدها بشكل صحيح.
- إلغاء الرمز (Token Revocation): إبطال الرموز التي تعرضت للاختراق أو فُقدت بسرعة.
- نطاق الرمز (Token Scope): تحديد حقوق الوصول وإدارتها بدقة.
- تخزين الرمز ونقله (Token Storage and Transmission): حفظ الرموز وإرسالها بأمان.
- تدفق رمز التفويض (Authorization Code Flow): تنفيذ هذا التدفق متعدد الخطوات وتشغيله بشكل صحيح.
- تسرب الرمز وانتحال الهوية (Token Leakage and Impersonation): منع الوصول غير المصرح به وتسرب البيانات.
- إدارة الرموز وتدقيقها (Token Management and Auditing): تتبع كيفية استخدام الرموز وما يحدث لها.
التفويض لا مفر منه تقريبًا دائمًا، لكن هناك حالات يمكن فيها الاستغناء عنه. فمثلًا، عند بناء MVP داخلي يكون فيه الأمان أقل أهمية، قد يسرّع التخلي عن التفويض المعقد تسليم الـ MVP دون المساس بالغرض منه.
ضعف بنية API
حتى مع متطلبات وظيفية وغير وظيفية رشيقة، قد ينتهي API بتعقيد مفرط إذا كانت بنيته غير كفؤة. يتناول هذا الجزء المبادئ والمفاضلات التي تساعد في تشكيل أفضل بنية API لحالة استخدام معينة.
تماسك API (API cohesion)
بما أن API هو نقطة الدخول إلى مكوّن، فإن مبادئ تماسك المكونات الموصوفة في كتاب “Clean Architecture” لروبرت مارتن تنطبق على تصميم API بالقدر نفسه. وعند نقلها إلى سياق API تبدو هذه القواعد كما يلي:
- REP (Release Equivalence Principle): ضع في API العناصر التي تُصدَر معًا كوحدة واحدة، وتجنب أن تتشارك عدة واجهات API رقم الإصدار نفسه
- CCP (Common Closure Principle): جمّع في API العناصر التي تتغير للأسباب نفسها وفي الوقت نفسه.
- CRP (Common Reuse Principle): ضمّن في API فقط الوظائف التي يعيد المدمجون استخدامها عادةً.
وكما يشير الكتاب، فإن هذه المبادئ “tend to fight each other”، لذا يجب موازنتها بعناية. وعند إسقاط مخطط الكتاب على واجهات API تظهر المفاضلات التالية:
إهمال REP (تكامل مؤلم): قد يمرّ المدمجون بتجربة سيئة لأنهم مضطرون إلى التكامل مع واجهات API كثيرة. وعليهم حينها التأكد من توافق هذه الواجهات مع بعضها، مما يجعل عملهم أكثر تعقيدًا وكلفة.
إهمال CCP (تطوير مؤلم): قد يصبح التطوير مرهقًا. وتجاهل هذا المبدأ يشير عادةً إلى ارتباط وثيق بين عدة واجهات API، وهو ما قد يبطئ API بشدة. وبسبب هذا الارتباط يجب تنسيق العمل على هذه الواجهات بعناية، مما يجلب تعقيدات وتحديات.
إهمال CRP (إصدارات مؤلمة): تجاهل هذا المبدأ يتركنا غالبًا مع API ثقيل تبنيه فرق عدة. وهذا يعني عادةً دورات إصدار طويلة ونطاقات تغيير واسعة، مما يزيد خطر إدخال الأعطال.
حبيبية نقاط النهاية (Endpoint granularity)
سؤال مهم آخر ينبغي طرحه:
كم عدد نقاط النهاية، وكم يغطي كل منها؟
الجواب البسيط: ينبغي أن تتضمن نقطة النهاية كل البيانات اللازمة لتلبية احتياجات العميل – ولا شيء أكثر من ذلك.
لكن هل يمكننا دائمًا تحقيق ذلك؟
عندما يوجد عدة عملاء باحتياجات مختلفة، قد يصعب تحقيق هذا التوازن. والمهم حقًا هو معرفة ما يحدث عندما تكون نقاط النهاية واسعة جدًا أو ضيقة جدًا.
لنعد إلى API المكتبة، ولننظر مثلًا إلى وظيفته التي تعيد معلومات عن المؤلفين وكتبهم المتاحة. إحدى طرق التنفيذ هي بناء نقطة نهاية تعيد كل البيانات عن الكتب والمؤلفين وأعمالهم:
{
"authors": [
{
"id": "704b1d68-3a85-4ec0-a4e6-8d7a936d4c02",
"name": "Robert C. Martin",
"availableBooks": [
{
"id": "c1bdc5c6-7a49-4c45-8e3c-2f47e65a0375",
"title": "Clean Code: A Handbook of Agile Software Craftsmanship",
"stock": 3,
"price": {
"amount": 15,
"currency": "USD"
},
"description": "Unlock the secrets
to writing pristine, maintainable, and
efficient code that stands the test of time.
Discover essential principles, patterns,
and best practices that empower you
to create software that is not only functional
but also a joy to read and work with.
Take your programming skills to the
next level with this indispensable
guide to achieving clarity, simplicity,
and excellence in your code."
},
{
"id": "e8c8a24b-5792-4d16-87d5-9e3c8e0b43e8",
"title": "Clean Architecture: A Craftsman Guide to Software Structure and Design",
"stock": 2,
"price": {
"amount": 20,
"currency": "USD"
},
"description": "Design Software Systems
for Maximum Maintainability and Flexibility.
Explore the principles and patterns
behind building clean, robust, and adaptable
software architectures, guided by industry
expert Robert C. Martin. Uncover the secrets
to crafting systems that stand the test of time,
fostering a deep understanding of architecture
design that empowers developers to create
software that is as elegant as it is efficient."
}
]
},
{
"id": "9b5f0b3e-820d-45c7-9847-eb3e3b33ab8f",
"name": "David Thomas",
"availableBooks": [
{
"id": "9d2bf831-7fe4-4fb3-ba8c-aa724ac5a773",
"title": "The Pragmatic Programmer: Your journey to mastery",
"stock": 5,
"price": {
"amount": 17,
"currency": "USD"
},
"description": "Your essential guide
to mastering the art of pragmatic
software development. Learn how
to approach coding challenges with
a practical mindset, leverage powerful
tools, and adopt efficient techniques
that lead to success in any programming
project. Unravel the secrets of
effective team collaboration, debugging,
and problem-solving to become
a highly skilled and adaptable developer.
Packed with timeless wisdom and real-world
advice, this book is your roadmap to
becoming a truly pragmatic programmer."
}
]
},
{
"id": "ccd61b63-9449-4186-b6f3-ae0fbc3d038a",
"name": "Andrew Hunt",
"availableBooks": [
{
"id": "9d2bf831-7fe4-4fb3-ba8c-aa724ac5a773",
"title": "The Pragmatic Programmer: Your journey to mastery",
"stock": 5,
"price": {
"amount": 17,
"currency": "USD"
},
"description": "Your essential guide
to mastering the art of pragmatic
software development. Learn how to
approach coding challenges with a
practical mindset, leverage powerful tools,
and adopt efficient techniques that
lead to success in any programming project.
Unravel the secrets of effective team
collaboration, debugging, and problem-solving
to become a highly skilled and adaptable
developer. Packed with timeless wisdom
and real-world advice, this book is your
roadmap to becoming a truly pragmatic
programmer."
}
]
}
]
}
خيار آخر هو استخدام نهج HATEOAS::
{
"authors": [
{
"id": "704b1d68-3a85-4ec0-a4e6-8d7a936d4c02",
"name": "Robert C. Martin",
"availableBooks": [
"/book-store-api/books/c1bdc5c6-7a49-4c45-8e3c-2f47e65a0375",
"/book-store-api/books/e8c8a24b-5792-4d16-87d5-9e3c8e0b43e8"
]
},
{
"id": "9b5f0b3e-820d-45c7-9847-eb3e3b33ab8f",
"name": "David Thomas",
"availableBooks": [
"/book-store-api/books/9d2bf831-7fe4-4fb3-ba8c-aa724ac5a773"
]
},
{
"id": "ccd61b63-9449-4186-b6f3-ae0fbc3d038a",
"name": "Andrew Hunt",
"availableBooks": [
"/book-store-api/books/9d2bf831-7fe4-4fb3-ba8c-aa724ac5a773"
]
}
]
}
يعتمد أي النهجين أفضل على السياق. فالأول يعطي بنية كاملة، لذا قد تكفي استدعاء API واحد لجلب كل ما يلزم. والمقابل هو حمولة استجابة أكبر وتوثيق أكثر تعقيدًا. أما الثاني فيُبقي البنية أبسط، لكن حتى المهام الأساسية، مثل سرد المؤلفين مع عناوين كتبهم، قد تتطلب عدة استدعاءات API. ويعتمد الاختيار على أمور مثل مدى تعقيد البيانات وجوانب الشبكة وتجربة المستخدم التي تريد تقديمها.
يبيّن هذا المثال أنه لا توجد إجابة صحيحة واحدة عن الحجم المناسب لنقطة نهاية معينة. لكن عند تصميم نقاط النهاية، من الحكمة أن تبقي هذه المفاضلة في ذهنك:
- إذا كانت نقاط النهاية صغيرة جدًا، فسيحتاج عملاء API إلى استدعاءات كثيرة للحصول على ما يريدون، مما يجعل التكامل أكثر تعقيدًا.
- وإذا كبرت نقطة النهاية أكثر من اللازم، فقد تؤدي الحمولة الكبيرة إلى أزمنة استجابة طويلة، وقد يصعب توثيق نقطة نهاية معقدة كهذه واستخدامها.
الخلاصة
تناول هذا المقال ما هو تعقيد API ولماذا يستحق الاهتمام. نظرنا في المشكلات التي قد تسببها واجهات API المعقدة وفي العوامل المؤثرة في تعقيد API، مثل المتطلبات الوظيفية وغير الوظيفية والتصميم غير الكفؤ لـ API. وكما رأينا، لا يمكن دائمًا تجنب التعقيد كليًا، لكن في حالات كثيرة توجد طرق لتقليله.
باختصار (TL;DR)
- قد تؤثر بساطة API في مدى انتشار تبنّيه.
- تقع مصادر تعقيد API عادةً ضمن مجموعات مثل المتطلبات الوظيفية والمتطلبات غير الوظيفية وضعف بنية API.
- اختر وظائف API بعناية.
- اقصر المتطلبات غير الوظيفية على ما تحتاجه فعلًا.
- اعتنِ ببنية API، مع مراعاة تماسك API وحبيبية نقاط النهاية.