التطوير باستخدام Ideanote

شكرًا لاهتمامك بالتطوير باستخدام Ideanote!

صُممت Ideanote بهيكل معياري ومرن منذ البداية لدعم مجموعة واسعة من حالات استخدام الابتكار. يتيح لك REST API، السهل التكامل، إنشاء مسارات عمل مخصصة للابتكار في مؤسستك، بدءًا من جمع الأفكار ووصولًا إلى إدارة الفرق ومزامنة البيانات.

مقدمة

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

تُحدَّد إصدارات API لضمان التوافق مع الإصدارات السابقة: الإصدار الحالي هو v1.

عنوان URL الأساسي الحالي لـ API هو https://api.ideanote.io/v1/.

يُرجى ملاحظة أن حقل معلمات الاستعلام في عنوان URL مطلوب لجميع نقاط النهاية.

حالات الاستخدام

يوفر Ideanote API مجموعة قوية من الأدوات لدمج إمكانات إدارة الأفكار في عمليات مؤسستك وبنيتها التحتية الحالية.

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

اطّلع على الأمثلة التالية:

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

من خلال الاستفادة من Ideanote API بهذه الطرق، يمكنك إنشاء منظومة ابتكار أكثر تكاملًا وكفاءة وتفاعلًا لمؤسستك.

أساسيات REST API

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

عنوان URL الأساسي لجميع استدعاءات API هو https://api.ideanote.io/v1/، وتُضاف مسارات محددة إلى عنوان URL الأساسي هذا للوصول إلى موارد مختلفة. على سبيل المثال، لسرد مهمات الأفكار، يُمدَّد عنوان URL ليشمل /v1/idea_collections.

يُعدّ المصادقة ضرورية لاستخدام Ideanote API، إذ يتطلب ذلك تضمين رمز وصول في ترويسة HTTP على النحو Authorization: Bearer YOUR_TOKEN. ويضمن ذلك الوصول الآمن إلى بيانات مساحة عملك، ضمن نطاق المستخدم الذي أنشأ رمز الوصول. بالإضافة إلى ذلك، يجب أن تتضمن جميع استدعاءات API ترويسة Accept: application/json، للإشارة إلى أن تنسيق تبادل البيانات هو JSON، وهو التنسيق الوحيد الذي يدعمه API.

يُنظَّم API حول الموارد، التي يُحدَّد موقعها في عنوان URL وتُعالَج باستخدام أفعال HTTP مثل GET وPOST وPUT وDELETE. وتشير هذه الأفعال إلى الإجراء الذي ترغب في تنفيذه، مثل الاستعلام أو الإضافة أو التحديث أو الحذف.

تؤدي المعلمات دورًا مهمًا في وظائف API، إذ تحدد معلمات الاستعلام تفاصيل طلبات GET، بينما تُستخدم بيانات المتن لطلبات PUT وPOST. ويتيح ذلك تفاعلات دقيقة مع API، مثل التنقل بين صفحات النتائج أو تحديث بيانات مورد بعينه.

تستخدم معالجة الأخطاء في Ideanote API رموز حالة HTTP القياسية للإشارة إلى نجاح الطلبات أو إخفاقها. وتشمل الرموز الشائعة 200 للنجاح، و400 للطلبات غير الصالحة، و429 لتجاوز حدود الاستخدام، و500 لأخطاء الخادم الداخلية.

بنية بيانات Ideanote

صُمِّمت بنية Ideanote لتعكس الطبيعة الهرمية والتعاونية للابتكار داخل الشركات. وتدعم هذه البنية نهجًا منظمًا لإدارة الأفكار، من نشأتها إلى تنفيذها، ضمن مساحة عمل رقمية مصممة لتحقيق الكفاءة.

فيما يلي، نستعرض المكونات الأساسية لبنية بيانات Ideanote لمساعدة المطورين على التنقل في المنصة والاستفادة منها بفاعلية.

مساحات العمل: مساحة العمل هي الطبقة العليا في Ideanote، وهي تنظّم كل ما يتعلق بالابتكار في مكان مركزي واحد لأفكار المؤسسة.

الأقسام: تقسّم الأقسام مساحة العمل إلى مناطق مرئية يسهل التعامل معها، مثل الإدارات أو الموضوعات المختلفة. وهذا يسهل تنظيم الابتكار في الشركة.

مجموعات الأفكار: مجموعات الأفكار هي أماكن تُجمع فيها الأفكار المتعلقة بموضوعات محددة. وهي تتضمن مراحل يجب أن تمر بها الفكرة، مما يساعد على تنظيم عملية التطوير من البداية إلى النهاية.

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

المستخدمون والفرق والرتب: في مساحة العمل، يكون المستخدمون هم المساهمين، ويمكن تجميعهم في فرق للتعاون. وللمستخدمين رتب مثل مالك مساحة العمل والمسؤول والعضو والضيف، تحدد مستوى صلاحياتهم في الإعدادات وإنشاء مجموعات الأفكار وإدارة المحتوى.

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

يمكن للمطورين العثور على مزيد من التفاصيل حول رتب المستخدمين وأذوناتهم لدى Ideanote في مركز المساعدة.

الوصول إلى API

للبدء باستخدام Ideanote API، ستحتاج إلى إنشاء رمز الوصول API ضمن الإعدادات > الحساب > رمز API في تطبيق Ideanote.

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

يمكنك امتلاك عدة رموز API لاستخدامها في تطبيقات مختلفة، ويمكن إلغاء كل رمز على حدة.

استخدام واجهات API لدينا مجاني للعملاء المشتركين في باقة مدفوعة.

أمثلة على استدعاءات API

سيوضح لك هذا البرنامج التعليمي كيفية إجراء أول استدعاء API إلى Ideanote API واسترداد قائمة بالأفكار من مجموعة أفكار.

الخطوة 1: إنشاء رمز وصول إلى API في Ideanote

إليك برنامجًا تعليميًا خطوة بخطوة حول التفويض

يجب تضمين هذا الرمز، المؤلف من 43 حرفًا، في ترويسة Authorization من النوع Bearer Token في جميع طلبات HTTPS التي ترسلها إلى API الخاص بـ Ideanote للوصول إلى المحتوى المحدد في حسابك. فيما يلي مثال على ترويسة التفويض:

Authorization: Bearer ea5b9e4********************

الخطوة 2: سرد مهمات الأفكار عبر API

استدعِ نقطة نهاية مجموعات الأفكار لعرض جميع مجموعات الأفكار التي يمكن للمستخدم الوصول إليها.

curl -X GET "https://api.ideanote.io/v1/idea_collections" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer <API Token>"

يعيد الأمر أعلاه بيانات JSON منسقة على النحو التالي:

[
    {
        "id": "020166b4-8846-4896-b2ac-9074fd3a1b2c",
        "title": "Example Idea Collection",
        "question": "How might we improve the coffee?",
        "details": null,
        "stats": {
            "ideas": {
                "total": 3
            }
        },
        "cover": {
            "url": {
                "thumbnail": "https://uploads.staging.ideanote.dev/staging/v1/f985c93c-bcbd-e67f-31e5-d54f965a5fe1/download_original"
            }
        }
    }
]

الخطوة 3: اختيار مهمة أفكار وسرد الأفكار

استدعِ نقطة النهاية لسرد الأفكار في مجموعة أفكار محددة. يملأ المثال أدناه المعرّف بالتنسيق هنا ويتضمن معلمات URL لإرجاع البيانات الوصفية وحقول الأفكار، بما في ذلك عناوين الحقول وأنواعها وقيمها.

curl -X GET "https://api.ideanote.io/v1/idea_collections/020166b4-8846-4896-b2ac-9074fd3a1b2c/ideas?fields=id,friendlyId,keywords,status.title,phase.name,fields.{kind,title,value},owner.{firstName}" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer <API Token>"

الخطوة 4: معالجة استجابة JSON

ستكون استجابة HTTPS قائمةً بالأفكار بتنسيق JSON.

يحتوي كل حقل فكرة على عنوان وقيمة. إذا كنت تبحث عن محتوى محدد، مثل وصف فكرة، فيمكنك البحث عن :id الذي يحمل ذلك العنوان، ثم معالجة قيمة حقل الفكرة هذا. تُدرَج حقول الأفكار بحسب معرّفاتها للحفاظ على اتساق API، حتى عند إعادة تسمية حقل فكرة في تطبيق Ideanote.

يمكنك تحديد معرّفات حقول الأفكار مسبقًا في تطبيق Ideanote ضمن Forms > Fields > Copy ID.

[
    {
        "id": "38494f31-4edc-414c-8320-e1aa8988e7aa",
        "friendlyId": 2,
        "keywords": ["bad", "idea", "bad", "idea"],
        "status": {
            "title": "On Track"
        },
        "phase": {
            "name": "Comment"
        },
        "fields": [
            {
                "kind": "LONG_TEXT",
                "title": "Description",
                "value": "This is a bad idea"
            },
            {
                "kind": "SHORT_TEXT",
                "title": "Title",
                "value": "Bad Idea"
            }
        ],
        "owner": {
            "firstName": "Test"
        }
    },
    {
        "id": "da011987-cfa9-49fa-b331-bb4ca0b2fa1b",
        "friendlyId": 1,
        "keywords": ["great", "idea", "great", "idea"],
        "status": {
            "title": "On Track"
        },
        "phase": {
            "name": "Comment"
        },
        "fields": [
            {
                "kind": "SHORT_TEXT",
                "title": "Title",
                "value": "Great Idea"
            },
            {
                "kind": "LONG_TEXT",
                "title": "Description",
                "value": "This is a great idea"
            }
        ],
        "owner": {
            "firstName": "Test"
        }
    }
]