الدرس 10: تصميم واجهة برمجة التطبيقات (API): إنشاء واجهات يطيب استخدامها

واجهة برمجة التطبيقات (API) هي الوجه العام للكود الخاص بك، سواء كانت نقطة نهاية HTTP أو دالة عامة داخل فئة. تحدد جودة هذه الواجهة الـVibe الذي يختبره مستهلكوها.

المبدأ 1: نقاط نهاية متوقعة وبديهية (واجهة API خارجية)

يجب أن تلتزم واجهات API الخارجية (مثل نقاط نهاية REST) بالاتفاقيات القياسية لتقليل الحمل المعرفي على المستخدمين الخارجيين.

استخدم الأسماء، وليس الأفعال، للموارد: /users وليس /getUsers.
استخدم أفعال HTTP للإجراءات: GET (استرداد)، POST (إنشاء)، PUT/PATCH (تحديث)، DELETE (إزالة).
بنية الاستجابة المتسقة: قم دائماً بإرجاع بيانات متوقعة، ورموز حالة، وتنسيقات أخطاء متسقة (مثل استجابة JSON بمفاتيح أخطاء متسقة).

المبدأ 2: واجهات داخلية بسيطة (إحساس DX)

عند تصميم واجهة فئة أو وحدة، اسعَ إلى البساطة. يجب ألا يحتاج المستهلكون إلى معرفة الآليات الداخلية المعقدة لاستخدامها.

قانون ديميتر (إحساس 'لا تتحدث مع الغرباء')

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

python

إحساس سيئ: ارتباط مُحكم، سلسلة طويلة

user.getAccount().getSubscription().getPlan().name

إحساس جيد: كائن المستخدم يلخص التعقيد

user.getSubscriptionPlanName()

المبدأ 3: الإعدادات الافتراضية والقيود المنطقية

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