لمدة عام ونصف ، قمنا بدمج API مع عشرين خدمة خارجية. مرت أول تكاملات الخمسة بالألم والدموع - لقد ارتكبنا جميع الأخطاء الممكنة. لقد أعادوا كتابة الكود عدة مرات ، افترقوا مع شركاء قبيل الإصدار ، لأنهم لم يتمكنوا من الاتفاق على التحسينات. الوقت الضائع والمال.
ولكن مع كل تكامل جديد ، توصلنا إلى حلول للمشاكل المتكررة. نتيجة لذلك ، حققنا التكامل الأخير أربع مرات أسرع من الأول. ماذا نفعل الآن بشكل مختلف - اقرأ المقال.
من أجل أن تفهم بشكل أفضل تفاصيل تكاملاتنا ، سنصف بإيجاز ما نقوم به. نحن نعمل على تطوير وسيط على الانترنت. مبدأ العمل: يأتي المستخدم إلى الموقع ، ويملأ الاستبيان ، وننقله إلى مؤسسات التمويل الأصغر ونتلقى موافقة أو رفضًا منه للحصول على قرض. يختار المستخدم عرضًا مناسبًا ويتلقى الأموال. لجعل هذا العمل عبر الإنترنت ، ندمج مع مؤسسات التمويل الأصغر عبر API.
تقييم استعداد الشريك للتكامل باستخدام قائمة مرجعية ومواصفات
سنقوم بتحليل سيناريوهين: عندما يكون لدى شريك محتمل بالفعل واجهة برمجة تطبيقات لقبول الطلبات ، وعندما لا يكون كذلك. يشير كلا السيناريوهين إلى أن الشريك يرغب في الاندماج معنا وأنه مستعد لقضاء بعض الوقت في هذا الأمر.
ليس للشريك واجهة برمجة تطبيقات - نرسل المواصفات
سبق أن أوضحنا للشريك ، شفهياً أو بالمراسلة ، ما نحتاجه للتكامل ، وقدم الشريك استنادًا إلى هذه التفسيرات واجهة برمجة تطبيقات لقبول الطلبات باستخدام Finspin. لم نتفق على متطلبات النماذج والكائنات وحقول الاستبيان وقواعد التحقق من صحتها. وصف بسرعة الغرض من الأساليب والإجابات المحتملة. كانت النتيجة بعيدة كل البعد عن المتوقع ، لأن فهمنا لواجهة برمجة التطبيقات كان مختلفًا تمامًا عن فهم الشراكة. اضطررت إلى إعادة كل شيء.
الان لقد كتبنا مواصفاتنا - ملف YAML الذي يمكن فتحه في Swagger. في المواصفات ، وصفنا واجهة برمجة التطبيقات (API) الأكثر ملاءمة لدمج Finspin مع مؤسسات التمويل الأصغر: حقول الاستبيان وقواعد التحقق من صحتها وتنسيقات وأنواع الطلبات مع الإجابات وأسماء الطريقة والأخطاء والحالات المحتملة. سجلنا حالة حالة التطبيق الذي نخطط لاستلامه ، على سبيل المثال: "مقبول للمعالجة" ، "قيد التقدم" ، "قرض مرفوض" ، "موافقة" ، إلخ.
نرسل المواصفات إلى الشريك ، ويقرر ما إذا كان يمكنه تقديم واجهة برمجة التطبيقات هذه. إذا لم يستطع ذلك ، يلاحظ نقاط إشكالية في المواصفات ، على سبيل المثال ، ليست كل حالات التطبيق جاهزة للنقل إلى واجهة برمجة التطبيقات أو لا توجد حقول كافية في الاستبيان. ونحن نناقش بالفعل نقاط محددة ، وليس كيانات مجردة. الشريك لا يضيع الوقت في كتابة مستنداته ، لكنه يضبط مستنداتنا.
لقد أمضينا يومين في إنشاء المواصفات ، لكننا نوفر الآن عشرات الساعات على الموافقات والتحسينات في واجهة برمجة التطبيقات. أيضًا ، بمساعدة المواصفات ، نقوم بسرعة بتصفية الشركاء غير المستعدين للتكامل. في المراحل المبكرة ، يصبح من الواضح أن عملياتنا لمعالجة الطلبات عبر الإنترنت مختلفة تمامًا: لا يمكن دمجها.
لدى الشريك واجهة برمجة تطبيقات - تعمل من خلال قائمة التحقق
اعتدنا على الحصول على مواصفات الشريك وطرح الأسئلة أثناء التنقل. غالبًا ما ينسون توضيح شيء مهم ، ثم ظهر هذا المهم في المراحل النهائية من التطوير والاختبار ، عندما أصبح الإصلاح وإعادة الكتابة باهظًا. بطريقة ما ، في نهاية التكامل مع شريك واحد ، اتضح أنه سينقل حالة القروض عبر واجهة برمجة التطبيقات مع تأخير لعدة أيام. بالنسبة لنا ، هذا غير مقبول. يجب التخلي عن الشراكة.
الان لقد كتبنا قائمة مرجعية لتقييم API والعمليات التي يقدمها. جمعت القائمة المرجعية الأسئلة التي يجب الإجابة عليها. أولاً ، يبحث مديرنا عن الإجابات في المواصفات. إذا لم يتم العثور على ، يعالج الأسئلة إلى الشريك.
تساعدك قائمة التحقق في العثور على الاختناقات قبل البدء في التطوير وليس بعد - عندما يتعين عليك تعديل الرمز ويعاني العملاء من سوء الخدمة.
نجدد باستمرار قائمة المراجعة عندما نواجه حالات جديدة. كلما كانت قائمة المراجعة أكثر تفصيلاً ، انخفض خطر تخطي الأخطاء في التطوير.
جزء المرجعية APIمسرد المصطلحات
في السابق ، بدا لنا أنه في مجال الإقراض عبر الإنترنت ، يفهم الجميع المصطلحات المهنية بنفس الطريقة ، لا يمكن أن يكون هناك أي تباينات. لقد أظهرت الممارسة أننا كنا مخطئين.
على سبيل المثال ، مع أحد مؤسسات التمويل الأصغر ، قمنا بتفسير العملاء الأساسيين وكرر العملاء بشكل مختلف. بالنسبة لنا ، العميل الأساسي هو العميل الذي دخل ملفه الشخصي أولاً إلى قاعدة بيانات MFI من خلال Finspin ، وكان العميل المتكرر موجودًا بالفعل في قاعدة البيانات. نظر الشريك في تكرار العملاء بعدد القروض التي تم إصدارها: تكرار تلقي قرضين وجاء في الثلث. مثل هذا الالتباس المصطلحي يمكن أن يؤدي إلى تضارب في التسويات المالية.
الآن نستخدم مسردًا صغيرًا للمصطلحات التي نتحقق من خلالها من خلال الشركاء. كقاعدة عامة ، يكفي توضيح خمس أو ست فصول أساسية من أجل مزامنة الأفكار حول التكامل وتقييم فرص التعاون.
بمجرد أن يساعدنا مسرد المصطلحات في تجنب التكامل غير المواتي. كان تفسيرنا لـ "موافقة" مختلفًا تمامًا عن الشركة التابعة. تضمنت "موافقة" الشريك العديد من الجوانب المختلفة التي تتطلب معالجة يدوية. نحن نسعى جاهدين لتحقيق أقصى قدر من التشغيل الآلي ، لذلك رفضنا على الفور التعاون.
توضيح مصطلح "الموافقة"العمل الأول ، ثم التنمية
كانت هناك حالات عندما بدأنا العمل مع شريك محتمل ذو مواصفات. تلقى مديرنا المواصفات ، درسها بعناية ، التفاصيل المحددة للتكامل مع الشريك ، وناقش القضايا المتنازع عليها مع المطورين. ثم جاءت رسالة من القيادة: "النهاية ، تم إلغاء التكامل ، لم نتفق على الشروط". موظف يضيع الوقت.
عندما تغير رأيك ، ويتم العملالآن أصبحت القاعدة الحديدية سارية: يبدأ المدير في دراسة المواصفات فقط عندما يتلقى قرارًا واضحًا بشأن التكامل من الإدارة.
الاستعداد للتكامل: عناوين url ، التفاصيل ، البيئة
في السابق ، حدثت أول مكالمة إلى API الشريك أثناء اختبار تطبيقنا ، من خوادم dev. في كثير من الأحيان الطلبات الأولى تلقى أخطاء في مرحلة إعداد الاتصال: لا يمكن الاتصال بالخادم أو مهلة فقط. الأسباب الأكثر شعبية:
- أسماء الطريقة غير الصحيحة (مختومة أو مشوشة)
- مجال غير صالح
- تفاصيل الاتصال الخاطئ ،
- لم نقم بإضافة عنوان IP الخاص بخوادمنا إلى القائمة البيضاء.
استغرق الأمر ساعات لإصلاح هذه الأخطاء الطفيفة ، لأنها ذهبت واحدة تلو الأخرى: حتى تقوم بإصلاح واحد ، فلن ترى التالي.
الآن ، قبل أخذ المهمة في خطة التطوير ، نقوم بتوضيح جميع ميزات الوصول إلى واجهة برمجة التطبيقات من خلال قائمة مراجعة صغيرة. تسرد قائمة المراجعة النقاط التي تحتاج إلى توضيح ، على سبيل المثال:
- القيود المفروضة على الحمل على الخدمة ،
- عدد الطلبات لكل وحدة الوقت
- تفاصيل الاتصال
- القائمة البيضاء بعناوين بروتوكول الإنترنت ،
- التحقق من صحة شهادة SSL
- متطلبات تشفير حركة المرور ،
- رؤوس خاصة في الطلبات
- وجود خادم اختبار مع API أو القدرة على إرسال طلبات الاختبار إلى خادم القتال
إذا كان هناك اختبار واجهة برمجة التطبيقات ، فسنكتشف بالتأكيد ما هو الفرق عند الوصول إلى خادم المعركة والاختبار. نحن نأخذ في الاعتبار الاختلافات عند بناء الطلبات من تطبيقنا إلى الشركاء في بيئات التطوير والإنتاج. تساعدنا هذه التدابير على فهم ما إذا كانت الأنظمة جاهزة لتلبية احتياجاتنا أو ما إذا كانت هناك حاجة إلى تعديلات إضافية.
إرسال الطلبات إلى واجهة برمجة التطبيقات يدويًا
قبل ذلك ، قمنا على الفور بكتابة الكود وفقًا لمواصفات الشريك ، ووضع المواصفات ، تم مراجعتها ، واختبارها. وفي مرحلة اختبارات التكامل ، اتضح أن ليس كل شيء مكتوب في المواصفات يتوافق مع الواقع - بدءًا من تنسيق الطلبات ، وينتهي بعملية تمرير التطبيق.
على سبيل المثال ، وفقًا للمواصفات ، عند الوصول إلى طريقة معينة ، نتوقع استجابة بتنسيق معيّن في الاستجابة ، وننهي المعالجة للتحقق من صحة الاستجابة المتلقاة ، ونذهب إلى الاختبارات ، وفجأة نحصل على صفيف في الاستجابة. نكتشف الأسباب من مطوري الشريك. أنها تشير إلى الوثائق التي عفا عليها الزمن. مرة أخرى ، دائرة من التحسينات والتعليقات والاختبارات.
الآن ، بمجرد أن نتلقى الوثائق وتفاصيل الاتصال ، نقوم بتشغيل العملية من خلال عميل API. عادةً ما يقوم المُختبِر بتحميل المواصفات إلى ساعي البريد ومحاكاة العملية التجارية الكاملة لإرسال طلب القرض ، والتحقق من الحالات الأكثر شيوعًا باستخدام مجموعات بيانات مختلفة للطلب. وهذا هو ، يدويا ما يفعله التطبيق ثم.
في مرحلة التشغيل اليدوي ، يتم الكشف عن 80 ٪ من الأخطاء في الوثائق. نصف الأخطاء وننقلها إلى الشريك. يقوم الشريك إما بإزالة عدم الدقة في المنزل ، أو إنهاء المواصفات. نتيجة لذلك ، بحلول وقت بدء العمل على الكود ، يتلقى المطورون مستندات العمل.
التناقضات الأكثر شعبية:
- تنسيق طلب غير صحيح ، وعد بقبول json ، اتضح أنه بحاجة إلى بيانات نموذجية ؛
- أخطاء في أسماء الحقول التي سيتم إرسالها في الطلب ؛
- أخطاء في تنسيقات الحقول ؛
- قواعد التحقق من صحة الحقل غير محددة أو يتم الإشارة إليها بشكل غير صحيح ؛
- قد يتم نسيان بعض الحقول تمامًا ؛
- مفقود أو مختلف عن الوصف الفعلي لتنسيق الاستجابة للطريقة ؛
- علامات خاطئة حول الحقول الإلزامية - "العلامات النجمية" يمكن أن تظهر حيث لا يكون الحقل إلزاميًا في الواقع ، والعكس صحيح ؛
- غالبًا لا يتم توثيق جميع الحالات والحالات التي قد يكون الكائن فيها ؛
- التناقضات بين الحالات المتوقعة والمتلقاة من الكائنات. على سبيل المثال ، في مرحلة ما ، نتوقع أن يكون التطبيق في الحالة X - وبواسطة API ، في الواقع ، نحصل على Y.
وصفة للسعادة: تجنب أخطاء تكامل واجهة برمجة التطبيقات
اكتب مواصفات للتكامل مع خدمتك. لقد أمضينا يومين في تطوير المواصفات في YAML ، لكننا الآن نوفر عشرات الساعات على التحسينات والموافقات.
إذا أرسل الشريك مواصفاته ، فتحقق من قائمة الاختيار. في قائمة المراجعة ، اجمع الأسئلة التي يجب أن تتلقى إجابات عليها. لا تعتمد على الخبرة والذاكرة ، فلا تزال تفوت شيئًا.
لديك مسرد للمصطلحات لتجنب الخلط مع شريك حياتك. أظهرت تجربتنا أن الاختلافات يمكن أن تكون بعبارات واضحة.
لا تأخذ المهمة في التطوير حتى تتلقى موافقة مبدئية من إدارة التكامل مع شريك. الفكرة واضحة ، لكنها تساعدنا على تجنب العمل غير الضروري.
افتح قائمة تحقق لتوضيح تفاصيل الوصول إلى واجهة برمجة التطبيقات الخاصة بالشريك: تفاصيل الاتصال ، والقائمة البيضاء ، والتحقق من صحة شهادة طبقة المقابس الآمنة ، ومتطلبات تشفير حركة المرور ، وما إلى ذلك. تحقق من قائمة التحقق في أقرب وقت ممكن لتجنب الانزلاق في المراحل النهائية.
حصلت على مواصفات - لا تتسرع في كتابة التعليمات البرمجية على الفور. أولاً ، قم بتشغيل العملية يدويًا من خلال عميل API ، على سبيل المثال ، من خلال ساعي البريد. لذلك ستجد أخطاء في المواصفات في مرحلة مبكرة وبموارد صغيرة. وسوف يكون.