إن بناء واجهات برمجة تطبيقات بدون مبادئ تصميم متسقة يؤدي إلى واجهات مربطة وتجربة مطورين ضعيفة. توفر هذه المهارة أنماط REST وGraphQL مثبتة لإنشاء واجهات برمجة تطبيقات قابلة للصيانة وموثقة جيدًا تتوسع مع احتياجاتك.
تنزيل ZIP المهارة
رفع في Claude
اذهب إلى Settings → Capabilities → Skills → Upload skill
فعّل وابدأ الاستخدام
اختبرها
استخدام "api-design-principles". تصميم نقاط نهاية لكتالوج منتجات التجارة الإلكترونية
النتيجة المتوقعة:
- GET /api/v1/products - سرد المنتجات مع الترقيم
- GET /api/v1/products/{id} - الحصول على تفاصيل المنتج
- POST /api/v1/products - إنشاء منتج (المشرف فقط)
- PUT /api/v1/products/{id} - استبدال المنتج (المشرف فقط)
- PATCH /api/v1/products/{id} - تحديث حقول المنتج (المشرف فقط)
- DELETE /api/v1/products/{id} - إزالة المنتج (المشرف فقط)
- GET /api/v1/products/{id}/reviews - سرد مراجعات المنتج
- GET /api/v1/categories/{id}/products - سرد المنتجات حسب الفئة
استخدام "api-design-principles". ما رموز حالة HTTP للسيناريوهات الشائعة؟
النتيجة المتوقعة:
- 200 OK - طلبات GET وPUT وPATCH الناجحة
- 201 Created - POST ناجح مع إنشاء المورد
- 204 No Content - DELETE ناجح أو استجابة فارغة
- 400 Bad Request - JSON غير صالح أو بناء جملة غير صحيح
- 401 Unauthorized - مصادقة مفقودة أو منتهية الصلاحية
- 403 Forbidden - مصادقة صالحة ولكن أذونات غير كافية
- 404 Not Found - المورد غير موجود
- 409 Conflict - تعارض الموارد (على سبيل المثال، مفتاح مكرر)
- 422 Unprocessable Entity - أخطاء التحقق من الصحة
- 429 Too Many Requests - تجاوز حد المعدل
- 500 Internal Server Error - فشل خادم غير متوقع
التدقيق الأمني
آمنStatic analysis flagged 201 patterns that are all false positives. The skill contains only documentation and educational content about API design. Markdown code blocks (backticks) were incorrectly identified as shell execution. Cryptographic references appear in security checklists, not actual implementations. URL and IP references are documentation examples for API endpoints. No executable code or security risks present.
درجة الجودة
ماذا يمكنك بناءه
تصميم واجهة برمجة تطبيقات جديدة
تصميم REST أو GraphQL API جديد من الصفر مع نمذجة الموارد المناسبة وهيكل نقطة النهاية ومعايير التوثيق قبل بدء التنفيذ.
مراجعة وإعادة هيكلة واجهة برمجة التطبيقات
تقييم نقاط نهاية واجهة برمجة التطبيقات الحالية مقابل مبادئ التصميم لتحديد أوجه عدم الاتساق وتحسين اتفاقيات التسمية وتخطيط استراتيجيات الترحيل.
توثيق معايير الفريق
إنشاء إرشادات تصميم واجهة برمجة التطبيقات على مستوى المؤسسة تغطي الإصدار والتعامل مع الأخطاء وأنماط المصادقة وتنسيقات الاستجابة لمحاذاة الفريق.
جرّب هذه الموجهات
أحتاج إلى تصميم نقاط نهاية REST لنظام مدونة مع المؤلفين والمنشورات والتعليقات. ساعدني في هيكلة تسلسل عناوين URL وطرق HTTP وتنسيقات الاستجابة مع اتباع أفضل ممارسات REST.
راجع مخطط GraphQL الخاص بي لنظام إدارة المستخدمين. تحقق من الاستخدام الصحيح للأنواع غير القابلة للقيم null وتنفيذات الواجهة واقترح تحسينات لكفاءة الاستعلام وتجنب مشاكل N+1.
واجهة برمجة التطبيقات الخاصة بي بها تغييرات جوهرية قادمة. قارن بين إصدار مسار URL وإصدار الرأس ونهج معلمة الاستعلام لحالة الاستخدام الخاصة بي. يتضمن توصيات الجدول الزمني للإيقاف.
صمم تنسيق استجابة خطأ متسق لـ REST API الخاص بي. يتضمن أخطاء التحقق على مستوى الحقل ورموز الأخطاء للتعامل البرمجي ورموز حالة HTTP المناسبة للسيناريوهات الشائعة.
أفضل الممارسات
- استخدم أسماء الجمع لمجموعات الموارد واجعل تسلسلات عناوين URL ضحلة (بحد أقصى 2-3 مستويات من التداخل)
- نفذ الترقيم المتسق مع حدود حجم الصفحة الموثقة وتضمين بيانات تعريف العدد الإجمالي في الاستجابات
- قم بإصدار واجهات برمجة التطبيقات من البداية باستخدام مسار URL أو إصدار الرأس، وحافظ على سياسة إيقاف واضحة للإصدارات الأقدم
تجنب
- استخدام الأفعال في نقاط النهاية مثل /createUser أو /getUserById بدلاً من طرق HTTP المناسبة على أسماء موارد الجمع
- إرجاع تنسيقات استجابة مختلفة أو أسماء حقول عبر نقاط نهاية متشابهة، مما يكسر توقعات العميل
- عناوين URL المتداخلة بعمق مثل /users/{id}/orders/{orderId}/items/{itemId}/reviews التي تقترن الموارد بإحكام شديد
الأسئلة المتكررة
هل يجب استخدام REST أو GraphQL لواجهة برمجة التطبيقات الجديدة الخاصة بي؟
كيف أتعامل مع إصدار واجهة برمجة التطبيقات بدون كسر العملاء الحاليين؟
ما نهج الترقيم الذي يجب استخدامه لمجموعات البيانات الكبيرة؟
كيف أصمم استجابات الأخطاء التي يمكن للمطورين استخدامها فعليًا؟
ما استراتيجية حد المعدل التي يجب تنفيذها؟
كيف أتعامل مع المصادقة في تصميم واجهة برمجة التطبيقات؟
تفاصيل المطور
المؤلف
sickn33الترخيص
MIT
المستودع
https://github.com/sickn33/antigravity-awesome-skills/tree/main/skills/api-design-principlesمرجع
main
بنية الملفات