تو کیا یہ RAML ہے یا OAS (Swagger)؟

مائیکرو سروسز کی متحرک دنیا میں، کچھ بھی بدل سکتا ہے — مختلف فریم ورک اور فن تعمیر کا استعمال کرتے ہوئے، کسی بھی جزو کو مختلف زبان میں دوبارہ لکھا جا سکتا ہے۔ صرف معاہدوں میں کوئی تبدیلی نہیں ہونی چاہیے تاکہ مائیکرو سروس کے ساتھ اندرونی میٹامورفوز سے قطع نظر، مستقل بنیادوں پر باہر سے بات چیت کی جا سکے۔ اور آج ہم معاہدوں کو بیان کرنے کے لیے فارمیٹ کے انتخاب کے اپنے مسئلے کے بارے میں بات کریں گے اور جو نمونے ہمیں ملے ہیں ان کا اشتراک کریں گے۔

پوسٹ تیار انا میلیخووا и ولادیمیر لیپٹین

مائیکرو سروسز۔ Acronis Cyber ​​Cloud تیار کرتے وقت، ہمیں احساس ہوا کہ ہم ان سے بچ نہیں سکتے۔ اور مائیکرو سروس ڈیزائن کرنا معاہدے کو باقاعدہ بنائے بغیر ناممکن ہے، جو مائیکرو سروس کے انٹرفیس کی نمائندگی کرتا ہے۔

لیکن جب ایک پروڈکٹ میں ایک سے زیادہ اجزاء ہوتے ہیں، اور معاہدے کی ترقی ایک باقاعدہ سرگرمی بن جاتی ہے، تو آپ مدد نہیں کر سکتے بلکہ عمل کی اصلاح کے بارے میں سوچنا شروع کر سکتے ہیں۔ یہ واضح ہو جاتا ہے کہ انٹرفیس (معاہدہ) اور عمل درآمد (مائیکرو سرویس) کو ایک دوسرے سے مماثل ہونا چاہیے، کہ مختلف اجزاء کو ایک ہی طریقے سے کام کرنا چاہیے، اور یہ کہ ان تمام فیصلوں کے مرکزی فیصلے کے بغیر، ہر ٹیم کو مجبور کیا جائے گا۔ ان کو حاصل کرنے کے لیے بار بار وقت گزاریں۔

ایمیزون مائیکرو سروسز ڈایاگرام منجانب ٹویٹ ورنر ووگیلس، سی ٹی او ایمیزون
مخمصہ کیا ہے؟ حقیقت میں، مائیکرو سروسز سے تعامل کرنے کے دو طریقے ہیں - گوگل کی جانب سے HTTP ریسٹ اور gRPC۔ گوگل کے ٹیکنالوجی اسٹیک میں پھنسنا نہیں چاہتے، ہم نے HTTP آرام کا انتخاب کیا۔ HTTP REST معاہدے کی تشریحات کو اکثر دو فارمیٹس میں سے ایک میں بیان کیا جاتا ہے: RAML اور OAS، جو پہلے Swagger کے نام سے جانا جاتا تھا۔ اس لیے، ہر ترقیاتی ٹیم کو معیارات میں سے کسی ایک کو منتخب کرنے کی ضرورت کا سامنا کرنا پڑتا ہے۔ لیکن جیسا کہ یہ پتہ چلتا ہے، یہ انتخاب کرنا بہت مشکل ہوسکتا ہے۔

تشریحات کی ضرورت کیوں ہے؟

تشریح کی ضرورت ہے تاکہ ایک بیرونی صارف آسانی سے اندازہ لگا سکے کہ اس کے HTTP انٹرفیس کے ذریعے آپ کی سروس کے ساتھ کیا کیا جا سکتا ہے۔ یعنی، بنیادی سطح پر، تشریح میں کم از کم دستیاب وسائل کی فہرست، ان کے HTTP طریقوں، درخواست کی باڈیز، پیرامیٹرز کی فہرست، مطلوبہ اور معاون ہیڈرز کا اشارہ، نیز واپسی کوڈز اور جوابی فارمیٹس کا ہونا ضروری ہے۔ معاہدے کی تشریح کا ایک انتہائی اہم عنصر ان کی زبانی وضاحت ہے ("اگر آپ اس استفسار کے پیرامیٹر کو درخواست میں شامل کرتے ہیں تو کیا ہوگا؟"، "کوڈ 400 کس صورت میں واپس کیا جائے گا؟")

تاہم، جب بڑی تعداد میں مائیکرو سروسز تیار کرنے کی بات آتی ہے، تو آپ تحریری تشریحات سے اضافی قدر نکالنا چاہتے ہیں۔ مثال کے طور پر، RAML/Swagger کی بنیاد پر، آپ پروگرامنگ زبانوں کی ایک بڑی تعداد میں کلائنٹ اور سرور دونوں کوڈ بنا سکتے ہیں۔ آپ مائیکرو سروس کے لیے خود بخود دستاویزات بھی حاصل کر سکتے ہیں اور اسے اپنے ڈویلپر پورٹل پر اپ لوڈ کر سکتے ہیں :)۔

ایک منظم معاہدے کی تفصیل کی مثال

معاہدہ کی تفصیل پر مبنی مائیکرو سروسز کی جانچ کرنے کا رواج کم عام ہے۔ اگر آپ نے تشریح اور ایک جزو دونوں لکھا ہے، تو آپ ایک آٹو ٹیسٹ بنا سکتے ہیں جو مختلف قسم کے ان پٹ ڈیٹا کے ساتھ سروس کی مناسبیت کو چیک کرتا ہے۔ کیا سروس جوابی کوڈ واپس کرتی ہے جو تشریح میں بیان نہیں کیا گیا ہے؟ کیا یہ واضح طور پر غلط ڈیٹا پر صحیح طریقے سے کارروائی کر سکے گا؟

مزید برآں، نہ صرف خود معاہدوں کا اعلیٰ معیار کا نفاذ، بلکہ تشریحات کو دیکھنے کے اوزار بھی مائیکرو سروس کے ساتھ کام کو آسان بنانا ممکن بناتا ہے۔ یعنی، اگر معمار نے معاہدے کو معیار کے مطابق بیان کیا، تو اس کی بنیاد پر، ڈیزائنرز اور ڈویلپرز اضافی وقت کے اخراجات کے بغیر دیگر مصنوعات میں سروس کو لاگو کریں گے۔

اضافی ٹولز کو فعال کرنے کے لیے، RAML اور OAS دونوں کے پاس میٹا ڈیٹا شامل کرنے کی صلاحیت ہے جو معیاری (مثال کے طور پر، OAS میں اس طرح کیا جاتا ہے۔).

عام طور پر، مائیکرو سروسز کے معاہدوں کے استعمال میں تخلیقی صلاحیتوں کی گنجائش بہت زیادہ ہے... کم از کم نظریہ میں۔

سانپ کے ساتھ ہیج ہاگ کا موازنہ

فی الحال، Acronis میں ترجیحی ترقی کا علاقہ Acronis سائبر پلیٹ فارم کی ترقی ہے۔ Acronis Cyber ​​Platform ایکرونس سائبر کلاؤڈ اور ایجنٹ کے حصے کے ساتھ تھرڈ پارٹی سروسز کے انضمام کے نئے نکات ہیں۔ اگرچہ ہم RAML میں بیان کردہ اپنے اندرونی APIs سے خوش تھے، لیکن API کو شائع کرنے کی ضرورت نے دوبارہ انتخاب کا سوال اٹھایا: ہمارے کام کے لیے کون سا تشریحی معیار استعمال کرنا بہتر ہے؟

ابتدائی طور پر، ایسا لگتا تھا کہ دو حل ہیں - سب سے زیادہ عام پیش رفت RAML اور Swagger (یا OAS) تھے۔ لیکن حقیقت میں یہ پتہ چلا کہ کم از کم 2 متبادل نہیں ہیں، لیکن 3 یا اس سے زیادہ ہیں۔

ایک طرف RAML ہے - ایک طاقتور اور موثر زبان۔ یہ درجہ بندی اور وراثت کو اچھی طرح سے لاگو کرتا ہے، اس لیے یہ فارمیٹ بڑی کمپنیوں کے لیے زیادہ موزوں ہے جن کو بہت زیادہ تفصیل کی ضرورت ہوتی ہے - یعنی ایک پروڈکٹ نہیں، بلکہ بہت سی مائیکرو سروسز جن میں معاہدوں کے مشترکہ حصے ہوتے ہیں - توثیق کی اسکیمیں، ایک جیسے ڈیٹا کی اقسام، ایرر باڈیز .

لیکن RAML کے ڈویلپر، Mulesoft نے Open API کنسورشیم میں شمولیت اختیار کر لی ہے، جو ترقی کر رہا ہے۔ گھماؤ. لہذا، RAML نے اس کی ترقی کو معطل کر دیا. ایونٹ کے فارمیٹ کا تصور کرنے کے لیے، تصور کریں کہ لینکس کے اہم اجزاء کے مینٹینرز مائیکروسافٹ میں کام کرنے کے لیے چھوڑ گئے ہیں۔ یہ صورت حال سویگر کو استعمال کرنے کے لیے ضروری شرائط پیدا کرتی ہے، جو متحرک طور پر ترقی کر رہا ہے اور تازہ ترین - تیسرے ورژن میں - عملی طور پر لچک اور فعالیت کے لحاظ سے RAML کے ساتھ ملتا ہے۔

ایک چیز کے لیے نہیں تو...

جیسا کہ یہ پتہ چلتا ہے، تمام اوپن سورس یوٹیلیٹیز کو OAS 3.0 میں اپ ڈیٹ نہیں کیا گیا ہے۔ گو میں مائیکرو سروسز کے لیے، سب سے اہم چیز موافقت کی کمی ہوگی۔ جانے والا معیار کے تازہ ترین ورژن کے لیے۔ تاہم، سویگر 2 اور سویگر 3 کے درمیان فرق ہے۔ بہت بڑا. مثال کے طور پر، تیسرے ورژن میں ڈویلپرز:

• تصدیقی اسکیموں کی بہتر وضاحت
• ختم JSON اسکیما سپورٹ
• مثالیں شامل کرنے کی صلاحیت کو اپ گریڈ کیا۔

صورتحال مضحکہ خیز ہے: معیار کا انتخاب کرتے وقت، آپ کو الگ الگ متبادل کے طور پر RAML، Swagger 2 اور Swagger 3 پر غور کرنے کی ضرورت ہے۔ تاہم، صرف سویگر 2 کو اوپن سورس ٹولز کے لیے اچھی سپورٹ حاصل ہے۔ RAML بہت لچکدار اور پیچیدہ ہے، اور Swagger 3 کو کمیونٹی کی طرف سے ناقص تعاون حاصل ہے، لہذا آپ کو ملکیتی ٹولز یا تجارتی حل استعمال کرنے ہوں گے، جو کافی مہنگے ہوتے ہیں۔

مزید برآں، اگر سویگر میں بہت ساری اچھی خصوصیات ہیں، جیسا کہ ایک ریڈی میڈ پورٹل editor.swagger.io، جس پر آپ ایک تشریح اپ لوڈ کر سکتے ہیں اور تفصیلی وضاحت، لنکس اور کنکشن کے ساتھ اس کا تصور حاصل کر سکتے ہیں، پھر زیادہ بنیادی اور کم دوستانہ RAML کے لیے ایسا کوئی موقع نہیں ہے۔ جی ہاں، آپ GitHub پر پروجیکٹس میں سے کچھ تلاش کر سکتے ہیں، وہاں ایک اینالاگ تلاش کر سکتے ہیں اور اسے خود تعینات کر سکتے ہیں۔ تاہم، کسی بھی صورت میں، کسی کو پورٹل کو برقرار رکھنا پڑے گا، جو بنیادی استعمال یا جانچ کی ضروریات کے لیے اتنا آسان نہیں ہے۔ اس کے علاوہ، swagger زیادہ "غیر اصولی"، یا زیادہ لبرل ہے - یہ کوڈ میں تبصروں سے پیدا کیا جا سکتا ہے، جو یقیناً API کے پہلے اصول کے خلاف ہے اور RAML کی کسی بھی یوٹیلیٹی کے ذریعے اس کی حمایت نہیں کی جاتی ہے۔

ایک وقت میں ہم نے RAML کے ساتھ ایک زیادہ لچکدار زبان کے طور پر کام کرنا شروع کیا، اور اس کے نتیجے میں ہمیں بہت ساری چیزیں خود کرنا پڑیں۔ مثال کے طور پر، منصوبوں میں سے ایک افادیت کا استعمال کرتا ہے ramlfications یونٹ ٹیسٹ میں، جو صرف RAML 0.8 کو سپورٹ کرتا ہے۔ لہذا ہمیں بیساکھیوں کو شامل کرنا پڑا تاکہ یوٹیلیٹی RAML ورژن 1.0 کو "کھائے"۔

کیا آپ کو منتخب کرنے کی ضرورت ہے؟

RAML کے حل کے ماحولیاتی نظام کو مکمل کرنے پر کام کرنے کے بعد، ہم اس نتیجے پر پہنچے کہ ہمیں RAML کو Swagger 2 میں تبدیل کرنے کی ضرورت ہے اور اس میں تمام آٹومیشن، تصدیق، جانچ اور اس کے بعد کی اصلاح کو انجام دینے کی ضرورت ہے۔ یہ RAML کی لچک اور Swagger سے کمیونٹی ٹولنگ سپورٹ دونوں کا فائدہ اٹھانے کا ایک اچھا طریقہ ہے۔

اس مسئلے کو حل کرنے کے لیے، اوپن سورس کے دو ٹولز ہیں جو معاہدے کی تبدیلی فراہم کرتے ہیں:

1. oas-raml-converter فی الحال غیر تعاون یافتہ یوٹیلیٹی ہے۔ اس کے ساتھ کام کرتے ہوئے، ہم نے دریافت کیا کہ اس میں پیچیدہ RAMLs کے ساتھ بہت سے مسائل ہیں جو فائلوں کی ایک بڑی تعداد میں "پھیل گئے" ہیں۔ یہ پروگرام جاوا اسکرپٹ میں لکھا گیا ہے اور ایک نحوی درخت کا بار بار چلنے والا عمل انجام دیتا ہے۔ ڈائنامک ٹائپنگ کی وجہ سے، اس کوڈ کو سمجھنا مشکل ہو جاتا ہے، اس لیے ہم نے فیصلہ کیا کہ مرنے والی یوٹیلیٹی کے لیے پیچ لکھنے میں وقت ضائع نہ کریں۔
2. webapi-parser - اسی کمپنی کا ایک ٹول جو دعویٰ کرتا ہے کہ وہ کسی بھی چیز اور ہر چیز کو اور کسی بھی سمت میں تبدیل کرنے کے لیے تیار ہے۔ آج تک، RAML 0.8، RAML 1.0 اور Swagger 2.0 کے لیے سپورٹ کا اعلان کیا گیا ہے۔ تاہم، ہماری تحقیق کے وقت، افادیت اب بھی تھی انتہائی گیلے اور ناقابل استعمال. ڈویلپرز ایک قسم کی تخلیق کرتے ہیں IR، انہیں مستقبل میں تیزی سے نئے معیارات شامل کرنے کی اجازت دیتا ہے۔ لیکن اب تک یہ صرف کام نہیں کرتا ہے۔

اور یہ وہ تمام مشکلات نہیں ہیں جن کا ہم نے سامنا کیا ہے۔ ہماری پائپ لائن میں سے ایک مرحلہ اس بات کی تصدیق کرنا ہے کہ ریپوزٹری سے RAML تفصیلات کے مطابق درست ہے۔ ہم نے کئی افادیت کی کوشش کی۔ حیرت کی بات یہ ہے کہ ان سب نے مختلف جگہوں پر اور بالکل مختلف برے الفاظ کے ساتھ ہماری تشریحات پر قسم کھائی۔ اور ہمیشہ پوائنٹ پر نہیں :)۔

آخر میں، ہم نے ایک پرانے پروجیکٹ پر طے کیا، جس میں کئی مسائل بھی ہیں (بعض اوقات یہ نیلے رنگ سے کریش ہو جاتا ہے، ریگولر ایکسپریشنز کے ساتھ کام کرتے وقت پریشانی ہوتی ہے)۔ اس طرح، ہمیں مفت ٹولز کی بنیاد پر توثیق اور تبدیلی کے مسائل کو حل کرنے کا کوئی طریقہ نہیں ملا، اور تجارتی افادیت کو استعمال کرنے کا فیصلہ کیا۔ مستقبل میں، جیسے جیسے اوپن سورس ٹولز زیادہ پختہ ہوتے جائیں گے، اس مسئلے کو حل کرنا آسان ہو سکتا ہے۔ اس دوران، "فائنشنگ" کے لیے محنت اور وقت کی لاگت ہمیں تجارتی سروس کی لاگت سے زیادہ اہم معلوم ہوئی۔

حاصل يہ ہوا

اس سب کے بعد، ہم اپنا تجربہ شیئر کرنا چاہتے تھے اور نوٹ کرنا چاہتے تھے کہ معاہدوں کو بیان کرنے کے لیے کوئی ٹول منتخب کرنے سے پہلے، آپ کو واضح طور پر اس بات کی وضاحت کرنے کی ضرورت ہے کہ آپ اس سے کیا چاہتے ہیں اور آپ کس بجٹ میں سرمایہ کاری کرنا چاہتے ہیں۔ اگر ہم OpenSource کے بارے میں بھول جاتے ہیں، تو پہلے سے ہی بڑی تعداد میں خدمات اور مصنوعات موجود ہیں جو آپ کو چیک کرنے، تبدیل کرنے اور توثیق کرنے میں مدد کریں گی۔ لیکن وہ مہنگے ہوتے ہیں، اور بعض اوقات بہت مہنگے ہوتے ہیں۔ ایک بڑی کمپنی کے لیے ایسے اخراجات قابل برداشت ہوتے ہیں، لیکن ایک اسٹارٹ اپ کے لیے یہ ایک بڑا بوجھ بن سکتے ہیں۔

ٹولز کے سیٹ کا تعین کریں جو آپ بعد میں استعمال کریں گے۔ مثال کے طور پر، اگر آپ کو صرف ایک معاہدہ ظاہر کرنے کی ضرورت ہے، تو Swagger 2 کو استعمال کرنا آسان ہو جائے گا، جس میں ایک خوبصورت API ہے، کیونکہ RAML میں آپ کو خود سروس بنانا اور برقرار رکھنا ہو گا۔
آپ کے پاس جتنے زیادہ کام ہوں گے، ٹولز کی ضرورت اتنی ہی وسیع ہوگی، اور وہ مختلف پلیٹ فارمز کے لیے مختلف ہیں، اور بہتر ہے کہ فوری طور پر دستیاب ورژنز سے خود کو واقف کر لیں تاکہ مستقبل میں آپ کے اخراجات کو کم سے کم کرنے کا انتخاب کیا جا سکے۔

لیکن یہ تسلیم کرنے کے قابل ہے کہ تمام ماحولیاتی نظام جو آج موجود ہیں وہ نامکمل ہیں۔ لہذا، اگر کمپنی میں ایسے پرستار ہیں جو RAML میں کام کرنا پسند کرتے ہیں کیونکہ "یہ آپ کو زیادہ لچکدار انداز میں خیالات کا اظہار کرنے کی اجازت دیتا ہے،" یا، اس کے برعکس، Swagger کو ترجیح دیتے ہیں کیونکہ "یہ صاف ہے"، تو بہتر ہے کہ انہیں کام پر چھوڑ دیا جائے۔ وہ اس کے عادی ہیں اور چاہتے ہیں، کیونکہ کسی بھی فارمیٹس کے ٹولز کو فائل کے ساتھ ترمیم کی ضرورت ہوتی ہے۔

جہاں تک ہمارے تجربے کا تعلق ہے، مندرجہ ذیل پوسٹس میں ہم اس بارے میں بات کریں گے کہ ہم اپنے RAML-Swagger فن تعمیر کی بنیاد پر کون سے جامد اور متحرک چیکس کرتے ہیں، ساتھ ہی ہم کنٹریکٹس سے کون سی دستاویزات تیار کرتے ہیں، اور یہ سب کیسے کام کرتا ہے۔

سروے میں صرف رجسٹرڈ صارفین ہی حصہ لے سکتے ہیں۔ سائن ان، برائے مہربانی.

مائیکرو سروس کے معاہدوں کی تشریح کے لیے آپ کون سی زبان استعمال کرتے ہیں؟

• RAML 0.8

• RAML 1.0

• اکڑ 2

• OAS3 (عرف)

• بلیو پرنٹ

• دیگر

• استعمال نہیں کرتے

100 صارفین نے ووٹ دیا۔ 24 صارفین غیر حاضر رہے۔

ماخذ: www.habr.com