تقدير المشروع
← كل المقالات

حافظ على بساطة واجهتك البرمجية: الطريق إلى الكفاءة وسهولة الاستخدام

واجهة API هي نقطة الدخول إلى أي أداة، لذا فإن ضبط تعقيدها أمر مهم. وحين يعتمد عملك على خدمات API، قد تصبح البساطة ميزة تنافسية.

23 دقائق قراءة
العمارة البرمجيةتطوير البرمجيات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."
    }
  ]
}

إن السماح للعميل باختيار عملة السعر يضيف تعقيدًا هنا ويجلب التحديات التالية:

  1. تقلب العملات: بما أن أسعار الكتب تعتمد على أسعار الصرف، فقد تكون غير مستقرة، مما قد يعني أن يرى العملاء أسعارًا غير متسقة.
  2. تعقيد سياسة الاسترجاع: قد تصبح سياسة استرجاع المشتريات بعملات مختلفة معقدة، لأن المبلغ المسترجع قد يتغير مع أسعار الصرف.
  3. آلية أسعار الصرف: يجب أن يوجد ما يجلب أسعار الصرف ويديرها حتى تكون تحويلات العملات صحيحة.
  4. معالجة الأعطال: يجب التعامل بسلاسة مع أخطاء جلب أسعار الصرف حتى لا تتعطل الخدمة.

يمكن التعامل مع كل هذه التحديات، لكن من المهم التفكير بعناية فيما إذا كانت القيمة التجارية لتوفير 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 بالامتثال لأنظمة واعتبارات مثل:

  1. أنظمة العملات المشفرة: بما أن العملات المشفرة تعمل على شبكات لامركزية، فقد يخضع استخدامها في المعاملات المالية لأنظمة محددة. وسيتعين على API الامتثال لقواعد العملات المشفرة المعمول بها، بما في ذلك متطلبات مكافحة غسل الأموال (AML) واعرف عميلك (KYC).
  2. أنظمة المحافظ الرقمية: مع المحافظ الرقمية قد يتعين على API اتباع القواعد التي يضعها كل مزوّد محفظة والتعامل مع بيانات العملاء – مثل بيانات الدفع والمعلومات الشخصية – بأمان. وفوق ذلك يأتي Apple Pay و Google Wallet بإجراءات استرجاع خاصة بهما، يجب التعامل معها بعناية وصحة.
  3. قوانين حماية البيانات والخصوصية: بمجرد إضافة وسائل دفع جديدة، يتعين على API معالجة أي مسائل حماية بيانات وخصوصية مرتبطة بمعالجة معلومات مالية وشخصية إضافية.
  4. معايير الأمان المالي: يجب أن يتبع API ممارسات الأمان المعتمدة في القطاع لحماية بيانات الدفع الحساسة ومنع الاحتيال أو الوصول غير المصرح به.
  5. موافقة المستخدم والاتفاقيات: بحسب وسيلة الدفع، قد يتعين على API الحصول على موافقة صريحة من المستخدمين لمعالجة المدفوعات بخيارات معينة واحترام أي اتفاقيات أو شروط خدمة مرتبطة بتلك الوسائل.

عند إضافة وسائل دفع جديدة إلى API المكتبة، على المؤسسة أن تقيّم هذه الالتزامات القانونية الجديدة وتفي بها بعناية. وقد يعني ذلك تحديث وظائف API وبروتوكولات الأمان ومعالجة المدفوعات لتلبية الأنظمة المنطبقة على وسائل الدفع المختارة. وإلى جانب تكاليف تطوير هذه الآليات، قد يتطلب الأمر توظيف مختصين قانونيين لضمان الامتثال الكامل.

الأداء (Performance)

يبرز جانبان رئيسيان عند الحديث عن أداء API: زمن الاستجابة الذي يقيس المدة التي تستغرقها معالجة طلب واحد، والإنتاجية (throughput) التي تقيس عدد الطلبات التي يستطيع API معالجتها في وحدة زمنية معينة. ويمكن تحسين الأداء بآليات متنوعة، منها مثلًا الترقيم (pagination) الذي يسترجع مجموعات البيانات الكبيرة ويعرضها بكفاءة، والتخزين المؤقت من جهة الخادم الذي يبقي البيانات كثيرة الطلب في متناول اليد ويقلل المعالجة المتكررة. وبفضل هذه التحسينات يمكن لـ API أن يستجيب أسرع ويخدم طلبات أكثر ويمنح المستخدمين تجربة أكثر سلاسة وتجاوبًا.

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

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

  1. إبطال التخزين المؤقت (Cache Invalidation): التأكد من تحديث التخزين المؤقت أو إبطاله فورًا عند تغير البيانات الأصلية، حتى لا يحصل العملاء على معلومات قديمة أو خاطئة.
  2. سياسات انتهاء الصلاحية: وضع سياسات انتهاء صلاحية مناسبة توازن بين حداثة البيانات وكفاءة التخزين المؤقت، بحيث لا تعيش البيانات المخزنة وقتًا أطول أو أقصر مما يلزم.
  3. اتساق البيانات: إبقاء البيانات المخزنة مؤقتًا متسقة مع مصدر الواجهة الخلفية لتجنب التناقضات وعدم تطابق البيانات.
  4. حجم التخزين المؤقت وإدارة الذاكرة: التحكم في حجم التخزين المؤقت واستخدام الذاكرة لتجنب الاستهلاك المفرط للموارد والحفاظ على قابلية النظام للتوسع.
  5. الأثر على الأداء: اختبار آلية التخزين المؤقت بدقة لقياس أثرها على أداء API وتجنب خلق اختناقات أداء جديدة.
  6. اعتبارات الأمان: معالجة مخاطر الأمان في تخزين البيانات الحساسة مؤقتًا بالتأكد من عدم حفظ المعلومات الحساسة في التخزين المؤقت وضبط ضوابط الوصول بشكل سليم.

يتطلب قرار إضافة آلية تخزين مؤقت تفكيرًا متأنيًا، لذا يجدر بك التفكير مرتين قبل المضي قدمًا.

التوافق مع الإصدارات السابقة (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>

يمكن أن يجلب دعم عدة صيغ عددًا من التحديات:

  1. يجب على مدمجي API تحديد نوع المحتوى الذي يريدون استلام البيانات به؛ وإن لم يفعلوا فسيحصلون على الصيغة الافتراضية، شرط أن تكون مضبوطة.
  2. يحتاج العملاء إلى توثيق جيد يشرح كيفية استخدام الصيغ المختلفة والتعامل معها بشكل صحيح.
  3. يجب تطبيق كل تغيير في API على جميع الصيغ المدعومة للحفاظ على اتساقها وتجنب التباينات.

وكما سبق، يجدر التساؤل عما إذا كان تحقيق متطلب قابلية النقل يقدّم قيمة تجارية كافية لتعويض الزيادة المحتملة في التعقيد.

الأمان (Security)

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

من أكثر طرق ترخيص العملاء شيوعًا استخدام JWT (JSON Web Token) مع آليات مثل OAuth 2.0. يوفر JWT طريقة مدمجة ومكتفية ذاتيًا لتمرير معلومات التفويض بين الأطراف، مما يجعله خيارًا شائعًا لتأمين تفاعلات API. أما OAuth 2.0 فيقدّم إطار تفويض موحّدًا يتيح تفويض حقوق الوصول إلى العملاء بأمان دون كشف بيانات الاعتماد الحساسة. وعند الجمع بينهما توفر هاتان التقنيتان أساسًا متينًا لحماية موارد API مع تسهيل منح وصول مضبوط للعملاء المصرح لهم.

ومع ذلك، يأتي تنفيذ JWT و OAuth 2.0 بمجموعة من التحديات والاعتبارات التي يجب التعامل معها بعناية للحفاظ على فعالية الأمان وسلامته، مثل:

  1. صلاحية الرمز وانتهاؤها (Token Validity and Expiry): إدارة أعمار الرموز وتجديدها بشكل صحيح.
  2. إلغاء الرمز (Token Revocation): إبطال الرموز التي تعرضت للاختراق أو فُقدت بسرعة.
  3. نطاق الرمز (Token Scope): تحديد حقوق الوصول وإدارتها بدقة.
  4. تخزين الرمز ونقله (Token Storage and Transmission): حفظ الرموز وإرسالها بأمان.
  5. تدفق رمز التفويض (Authorization Code Flow): تنفيذ هذا التدفق متعدد الخطوات وتشغيله بشكل صحيح.
  6. تسرب الرمز وانتحال الهوية (Token Leakage and Impersonation): منع الوصول غير المصرح به وتسرب البيانات.
  7. إدارة الرموز وتدقيقها (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 وحبيبية نقاط النهاية.