التكنولوجيا
الأعمال
الشركات الناشئة
الحوسبة السحابية
شركة ناشئة
التوثيق
تكامل واجهة برمجة التطبيقات
API Documentation
لديك مشروع تقني Startup "تطبيق جوال / أنظمة سحابية SaaS / نظام إلكتروني مثل ERP - POS - CRM" وترغب في إتاحة ال API للربط والتكامل مع أنظمة أخرى بهدف إضافة مصادر دخل Revenue Stream💰وكسب شريحة أكبر من العملاء؟🧐
👌من المهم توثيق وشرح استخدام ال API باحترافية
#مساحة_التقنية
#ثريد
👌من المهم توثيق وشرح استخدام ال API باحترافية
#مساحة_التقنية
#ثريد
أولاً: لمن نوثق ال API؟
يجب في عملية التوثيق مراعاة اختلاف فئات من سيقرأون التوثيق، وهما:
١- صُناع القرار " مثل المدير التقني CTO - ومدير المشروعات PM - محللين الأعمال - رواد الأعمال أنفسهم ومستشاريهم"
٢- التقنيين "المبرمجين Developer - فريق الحماية Security - المخترقين😀"
يجب في عملية التوثيق مراعاة اختلاف فئات من سيقرأون التوثيق، وهما:
١- صُناع القرار " مثل المدير التقني CTO - ومدير المشروعات PM - محللين الأعمال - رواد الأعمال أنفسهم ومستشاريهم"
٢- التقنيين "المبرمجين Developer - فريق الحماية Security - المخترقين😀"
ثانياً: كيف تجذب انتباه جميع الفئات؟
١- إشرح المزايا البزنس التي ستعود على صانع القرار من اتخاذ قرار الربط مع ال API الخاصة بك، مثلاً إذا عندك نظام فاتورة إلكترونية فمن المهم يضاح ماذا سيستفيد صاحب المتجر من الربط بنظامك
٢- حدد كيف نبدأ، لا تجعله يستكشف بنفسه كي لا يتحول لمنافسك
١- إشرح المزايا البزنس التي ستعود على صانع القرار من اتخاذ قرار الربط مع ال API الخاصة بك، مثلاً إذا عندك نظام فاتورة إلكترونية فمن المهم يضاح ماذا سيستفيد صاحب المتجر من الربط بنظامك
٢- حدد كيف نبدأ، لا تجعله يستكشف بنفسه كي لا يتحول لمنافسك
٣- اكتب تعليمات متسلسلة لأشهر العمليات، مثلاً وضح للمبرمج أنه سيقوم بربط المنتجات والمستخدمين، ثم سيقوم بإنشاء فاتورة بعد اتمام تنفيذ الربط، لتجعله فاهم وتحافظ له على وقته وجهده
٤- استخدم لغة المحادثة والحوار conversational tone واستخد لغة انجليزية سلهة وكأنه يقرأ قصة شيقة ممُتعة
٤- استخدم لغة المحادثة والحوار conversational tone واستخد لغة انجليزية سلهة وكأنه يقرأ قصة شيقة ممُتعة
٥- في حال توجد عندك مصطلحات أو خدمات خارجية مثل مكتبات OAuth و npm أو كيفية عمل تشفير من طرف الخادم أضف له روابط تشرح كيفية استخدامها من مصدرها.
ثالثاً: تصميم التوثيق Layout:
١- استخدم تصميم ديناميكي يتم عرضه على شاشات الكمبيوتر والجوال Responsive
ثالثاً: تصميم التوثيق Layout:
١- استخدم تصميم ديناميكي يتم عرضه على شاشات الكمبيوتر والجوال Responsive
٢- يُفضل التصميم باستخدام ال ٣ أعمدة Three-column layout، عمود للفهرس، وعمود للتفاصيل، وعمود لتجربة الكود.
٣- استخدم التنبيهات والتوضيحات Sticky contents لشرح نقاط محددة ترى أنها تحتاج ايضاح.
٣- استخدم التنبيهات والتوضيحات Sticky contents لشرح نقاط محددة ترى أنها تحتاج ايضاح.
رابعاً: أشهر أدوات توثيق ال API:
- Swagger
- API Blueprint
- Postman
- RAML
- Stoplight
خامساً: كيف تُستخدم ال API؟
عندما استخدم API خاصة بك بعد قراءة التوثيق الذي أعددته فمن الأفضل أن اتبع هذه الخطوات لاستخدام ال API بشهولة
- Swagger
- API Blueprint
- Postman
- RAML
- Stoplight
خامساً: كيف تُستخدم ال API؟
عندما استخدم API خاصة بك بعد قراءة التوثيق الذي أعددته فمن الأفضل أن اتبع هذه الخطوات لاستخدام ال API بشهولة
١- حمل الكود Download this code
٢- غير رمز الحماية الخاص بك Replace your API key
٣- استخدم الكود Run the code
إذا تطلب الأمرر أكثر من ذلك فآعتقد أن لم تحترف عملية توثيق ال API
٢- غير رمز الحماية الخاص بك Replace your API key
٣- استخدم الكود Run the code
إذا تطلب الأمرر أكثر من ذلك فآعتقد أن لم تحترف عملية توثيق ال API
سادساً: مراقبة الاستخدام Monitoring API Usage:
١- تأكد من أن لديك نظام فوترة ومدفوعات للتعامل المباشر مع استخدام ال API، مثلاً الاشتراك الشهري، أو شراء عمليات سحب أكثر في حال انتهى حدي
٢- وضضح ما هو حد السحب اليومي / الشهري للاتصال بال API
١- تأكد من أن لديك نظام فوترة ومدفوعات للتعامل المباشر مع استخدام ال API، مثلاً الاشتراك الشهري، أو شراء عمليات سحب أكثر في حال انتهى حدي
٢- وضضح ما هو حد السحب اليومي / الشهري للاتصال بال API
٣- تأكد من وجود نظام تنبيهات يُشعر المستخدم بقرب انتهاء استخدام الحد المسموح به.
سابعاً: اهتم بقراءة كيفية حوكمة ال API من هذا الرابط blog.api.rakuten.net
ثامناً: اتبع قواعد بناء ال API المُعترف بها حتى لا يكون ال API الخاص بك شاذ عن الآنظمة الأخرى
swagger.io
سابعاً: اهتم بقراءة كيفية حوكمة ال API من هذا الرابط blog.api.rakuten.net
ثامناً: اتبع قواعد بناء ال API المُعترف بها حتى لا يكون ال API الخاص بك شاذ عن الآنظمة الأخرى
swagger.io
جاري تحميل الاقتراحات...