🙎🏼 🌦️ 🛅 API Style Guide ، أو لا تجعل المستخدمين يفكرون 👩‍🍳 🚶 🎟️

مرحبا! اسمي ليشا روتسكوي وأنا مدير منتجات في Wrike. قبل ذلك ، كان يعمل في Adform و PandaDoc. طوال السنوات الخمس الماضية ، كنت أفعل كل ما يتعلق بعمليات التكامل وواجهات برمجة التطبيقات.

Wrike هو أحد منتجات SaaS للتعاون وإدارة المشاريع. نريد للمطورين أن يبنوا حلولهم على أساس Wrike ، ولهذا نحتاج إلى واجهة برمجة التطبيقات الخاصة بنا لتكون مريحة. في الوقت نفسه ، لدينا 9 مكاتب حول العالم ، و 3 منها مكاتب تطوير. من الصعب جدًا إنشاء واجهة برمجة تطبيقات متسقة باستخدام فرق موزعة تتحدث لغات مختلفة. هناك احتمال متزايد أن تبدأ قراراتهم في تناقض بعضهم البعض. في هذه الحالة ، لا يمكن للمرء الاستغناء عن مجموعة موحدة من القواعد للجميع.

إذا كنت تعمل أيضًا بطريقة موزعة وقمت بإنشاء واجهة برمجة تطبيقات خاصة بك ، فإن Style Guide API يمكنها مساعدتك. أريد أن أخبرك ما هي المشاكل الشائعة التي يحلها وكيف تجعل الحياة أسهل للمطورين. سأشارك أيضًا تجربتي في كتابة وتنفيذ دليل نمط API الخاص بي في الشركة.

لماذا نحتاج إلى واجهة برمجة تطبيقات ملائمة؟

ربما اضطر العديد من القراء إلى حل المشكلات باستخدام واجهة برمجة التطبيقات غير المناسبة. نعم ، هذه ليست بسيطة للغاية وتستغرق المزيد من الوقت ، ولكن لا يزال بإمكانك عادةً حل المشكلة.

ثم لماذا تضيع الوقت وجهد الفريق لجعل API أفضل؟ الجواب بسيط للغاية: في كثير من الأحيان يتم اتخاذ القرار بشأن استخدام منتجك من قبل المطورين ، خاصة عندما يتعلق الأمر بواجهات برمجة التطبيقات والتكامل. لذلك ، من المهم التفكير ليس فقط في تجربة المستخدم (UX) ، ولكن أيضًا في تجربة DX - developer.

سوف أعطي مثالا على ذلك. عملت مرة في فريق كان مسؤولاً عن جميع عمليات دمج المنتجات. غالبًا في منتصف الربع ، عندما تم تحديد خططنا بالفعل ، أتى أحد المسوقين وقال: "لقد صنعت Z سوقًا جديدًا وستطلق الإصدار التالي من منصتها. قريباً سيكون لديهم حدث عام رائع حيث يمكننا التحدث عن اندماجنا ونجاحنا! سيكون من الرائع أن نكتب هذا الدمج بسرعة الآن ". ماذا فعلنا في هذه الحالة؟ إذا استطاع مطور ذو خبرة في فريق عمل الحد الأدنى من النموذج الأولي في غضون ثلاثة أيام ، فغالبًا ما نجحنا في خلال أسبوعين أو ثلاثة في جعل المهمة في حالة ممتازة. إذا كانت أيام قليلة مفقودة ، فإن واجهة برمجة التطبيقات والوثائق كانت كذلك.كان من غير المجدي بالنسبة لنا إعادة رسم الخطط والقيام بدمج جديد - على الرغم من كل ذلك ، لم يكن هناك شيء جدير بالاهتمام بحلول الموعد المحدد. تذكر أن منتجك قد يكون في هذه الحالة - سيقرر الشركاء ما إذا كان سيتعامل معك أم لا اعتمادًا على مدى سرعة وسهولة بدء العمل مع API الخاص بك.

ولكن لا يكاد أي شخص يريد تصميم واجهة برمجة تطبيقات سيئة. لماذا يختلف الجميع؟ عادة ، تتطور API مثل هذا. عندما تبدأ شركة ناشئة في النمو ويأتي إليها العملاء الأوائل ، تقوم إحدى الفرق بتحديد نقطة النهاية وتقرر نقل الإصدار إلى عنوان URL:

يظهر العملاء الجدد تدريجياً والاحتياجات الجديدة. يتم تضمين اللاعبين من الفريق الثاني في العمل ، الذين يعتقدون أنه من الأفضل استخدام أنواع الوسائط الخاصة بهم للإصدار:

بعد فترة ، يصل الفريق الثالث. في المؤتمر ، يتعلمون أن Stripe يقوم بإصدار API الخاص به بتواريخ إصدار رئيسية. وقرروا أن يفعلوا الشيء نفسه:

والنتيجة هي واجهة برمجة التطبيقات التي توجد بها ثلاث طرق للإصدار. تعمل جميع الطرق ، ولكنها تعمل بشكل مختلف.

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

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

بشكل عام ، تقوم رسائل الخطأ بكل شيء بشكل مختلف. على سبيل المثال ، مثل هذا:

أو على هذا

النحو : هناك أيضًا رسالة الخطأ المفضلة - إجابة فارغة:

حسنًا ، مجرد كلاسيكي - الإجابة هي 200 OK ، يوجد داخلها JSON مع وصف للأخطاء التي حدثت.

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

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

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

كيف تصنع دليل نمط API الخاص بك؟

قام Arnauld Lauret (المعروف باسم API Handyman ) بإنشاء موقع رائع - API Stylebook . لقد وضع دليل أسلوب يمكن الوصول إليه بشكل عام ، والذي وضعته العديد من الشركات (Cisco و Google و Red Hat والوكالات الحكومية والعديد من الشركات الأخرى) في المجال العام.

تنقسم الإرشادات إلى مواضيع على الموقع. على سبيل المثال ، إذا كنت مهتمًا بالإصدار ، فيمكنك على علامة التبويب "الإصدار" معرفة كيفية حل الشركات المختلفة لهذه المشكلة.

تعلم من تجربة الآخرين! لكن نسخ دليل دليل شخص آخر تمامًا ليس فكرة جيدة. ومع ذلك ، فهو يحل مشاكل شركة أخرى ، وليس شركتك.

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

ما الذي يجب تضمينه أيضًا في Style Guide API

أيضًا ، يجب أن يتضمن دليل الأسلوب القيم الأساسية والأساليب الهندسية التي تلتزم بها الشركة.

ماذا يمكن أن يكونوا؟

Write APIs in English. , . - , , . Style Guide, , .
API First principle. API : , , frontend-. , API . , , .
استخدم REST و JSON. قد يكون هذا مهمًا إذا كنت تريد أن يستخدم أوسع جمهور ممكن واجهة برمجة التطبيقات أو النظام الأساسي الخاص بك. على الرغم من حقيقة أن GraphQL أصبحت شائعة بشكل متزايد منذ عام 2017 ، إلا أن الجميع لا يعرفون ذلك. معظم المطورين ، على الأرجح ، لم يستخدموها أبدًا ، مما يعني أنهم سيزيدون من وقت الغمر والتطوير. لماذا خلق التعقيد؟

علاوة على ذلك ، يمكن وضع المبادئ الأساسية حول المواضيع. على سبيل المثال ، داخل مبدأ استخدام REST و JSON ، يمكنك بسهولة تحديد الموضوعات التي يجب وصفها في الدليل:

تفضل REST API مع حمولات JSON
- طلبات HTTP
- رموز حالة HTTP
- جسون

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

طلبات HTTP
- يجب استخدام طرق HTTP بشكل صحيح
- يجب أن تتبع رؤوس HTTP المخصصة مصطلحات التسمية

يعجبني حقًا النهج الذي يصف الحاجة إلى اتباع القواعد من خلال الأفعال يجب أو يجب أو ربما (مستعارة من RFC 2119 ). ثم يميز كل شخص يقرأ دليل الأسلوب بين القواعد والتوصيات الإلزامية.

إليك كيف تبدو ، على سبيل المثال ، في زالاندو :

أشياء يجب وضعها في الاعتبار عند بدء تشغيل دليل الأسلوب

. , . , , . , , . API management , . API.
. - 15- . rate limiting, .. — , , - .
. , OAuth, REST. , , , scopes .
. , , .
. , . , . . . , .
. , , .
. , , .. : , «user», , «user», .
. , — . , (OpenAPI-, -) . .

API Style Guide?

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

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

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

كيف نفذ الفريق واجهة برمجة تطبيقات Style Guide؟

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

من الصعب للغاية على فريق واحد في شركة كبيرة تنفيذ مثل هذه التغييرات الهامة. بحاجة إلى دعم. هنا تم ربط أبطال واجهة برمجة التطبيقات - المهندسون المعماريون والتقليديون من كل اتجاه الذين ساعدوا في دمج الفكرة في فرقهم وأقسامهم.

عندما تحدث التغييرات الرئيسية ، غالبًا ما يظهر السخط. في هذه الحالة ، تحتاج إلى سلطة يمكنها إقناع هؤلاء بالحاجة إلى التغيير. Tehlids هم أنسب الناس لهذا.

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

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

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

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

حاولنا تقديم كل هذا في تأهيل معظم الفرق في الشركة ، بما في ذلك الفرق غير الهندسية. هذا ضروري أيضًا حتى يفهم الجميع متى وفي أي الحالات ومن يمكن أن تأتي للمساعدة.

التشغيل الآلي

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

يمكن أن تساعد بعض الأدوات في ذلك:

Zally من الشيكات زالاندو لمعرفة ما إذا كانت مواصفات OpenAPI مباريات API الخاص دليل نمط. يتحقق التكوين الأساسي لـ Zally من الامتثال لدليل Zalando Style ، ولكن يمكنك إعادة تعريف وإضافة القواعد الخاصة بك.
يتحقق Apedd 's Dredd لمعرفة ما إذا كان التنفيذ النهائي لـ REST API يتطابق مع تصميمك ، أي مواصفات OpenAPI أو Blueprint أو RAML.

هذه المقالة هي نص محادثتي مع مؤتمر مطوري منصة ميرو . يمكنك العثور على فيديو الخطاب هنا .

يسعدني أن أجيب على أسئلتك حول تنفيذ دليل نمط واجهة برمجة التطبيقات. سيكون الأمر رائعًا أيضًا إذا شاركت تجربة مماثلة!

شكر خاص إلى داريا إيفانوفا لمساعدتها في إعداد هذا المقال!