Optifora کا API کیسے کام کرتا ہے
یہ صفحہ API کی ساخت بیان کرتا ہے: شناخت کیسے ثابت ہوتی ہے، ورژن کیسے آگے بڑھتے ہیں، ایک درخواست کن حدود کے اندر رہتی ہے، خرابی کیسی دکھائی دیتی ہے، اور بیرونی دنیا کے ساتھ ڈیٹا کا تبادلہ کیسے ہوتا ہے۔
پروڈکٹ ابھی زیر تیاری ہے اور API کی سطح مکمل کی جا رہی ہے۔ اینڈ پوائنٹس کی حوالہ دستاویز الگ سے شائع کی جائے گی؛ اس صفحے پر کوئی پتہ اور کوئی نمونہ کال نہیں، صرف طریقہ کار ہے۔
شناخت کی تصدیق
ہر درخواست یا تو کسی شخص کی ہوتی ہے یا کسی رجسٹرڈ ایپلی کیشن کی۔ شناخت کے بغیر آنے والی درخواست جب کسی محفوظ اینڈ پوائنٹ تک پہنچتی ہے تو غیر تصدیق شدہ قرار پا کر واپس ہوتی ہے۔
- بیئرر ٹوکنرسائی ٹوکن درخواست کی اجازت ہیڈر میں سفر کرتا ہے۔ یہ دستخط شدہ ہوتا ہے اور صرف اتنا بتاتا ہے کہ درخواست کس کی ہے۔
- مختصر معیادرسائی ٹوکن کی معیاد منٹوں میں ناپی جاتی ہے؛ یہ مدت تنصیب کی ایک ترتیب ہے اور طے شدہ طور پر تیس منٹ ہے۔
- تجدید اور گردشسیشن کو ریفریش ٹوکن سے بڑھایا جاتا ہے، اور ہر توسیع پر نیا جوڑا جاری ہوتا ہے۔ اگر استعمال شدہ ریفریش ٹوکن دوسری بار پیش کیا جائے تو اس شخص کے تمام سیشن منسوخ کر دیے جاتے ہیں۔
- اجازتیں ٹوکن کے اندر درج نہیں ہوتیںٹوکن صرف شناخت اٹھاتا ہے؛ کوئی شخص کیا دیکھ سکتا ہے، یہ ہر درخواست پر ڈیٹابیس سے پوچھا جاتا ہے۔ اس لیے واپس لی گئی اجازت، ہاتھ میں موجود ٹوکن کی معیاد ختم ہونے سے پہلے ہی کام کرنا چھوڑ دیتی ہے۔
- انٹیگریٹر کی کلیدرجسٹرڈ ایپلی کیشن اپنی مخصوص کلید کے ساتھ جڑتی ہے۔ کھلی قدر صرف ایک بار، بناتے وقت دکھائی جاتی ہے؛ محفوظ صرف اس کا ہیش اور وہ غیر خفیہ سابقہ رہتا ہے جس سے کلید پہچانی جاتی ہے۔
- رسائی ادارہ دیتا ہےکوئی ایپلی کیشن کتنی ہی عام کیوں نہ ہو، ادارے کی درج کردہ اجازت کے بغیر وہ ایک سطر بھی نہیں دیکھتی۔ یہ اجازت تاریخ رکھتی ہے، اس کا دائرہ متعین ہے اور اسے واپس لیا جا سکتا ہے۔
ورژن بندی
- ورژن راستے میں رہتا ہےاینڈ پوائنٹس ورژن کے سابقے کے پیچھے شائع ہوتے ہیں؛ آج کی سطح ورژن ایک ہے۔
- توڑنے والی تبدیلی نیا راستہ کھولتی ہےکسی موجودہ اینڈ پوائنٹ کا معاہدہ اپنی جگہ توڑا نہیں جاتا۔ ناہم آہنگ تبدیلی نئے ورژن کے راستے پر شائع ہوتی ہے جبکہ پرانا چلتا رہتا ہے۔
- دستاویز اپنا ورژن خود بتاتی ہےحوالہ دستاویز پر وہ ورژن نمبر درج ہوتا ہے جس سے وہ تیار ہوئی؛ آپ کون سا ورژن پڑھ رہے ہیں، اس کا جواب دستاویز خود دیتی ہے۔
ماحول اور حدود
حوالہ دستاویز دو ماحول کا اعلان کرتی ہے: پیداواری اور مقامی ترقیاتی۔ بنیادی پتہ انٹیگریٹر کو اس کی کلید کے ساتھ دیا جاتا ہے؛ اس صفحے پر شائع نہیں ہوتا۔
- زندگی اور آمادگی الگ الگ ناپی جاتی ہیںایک اینڈ پوائنٹ بتاتا ہے کہ عمل چل رہا ہے؛ دوسرا ڈیٹابیس کو ایک حقیقی سوال بھیج کر تصدیق کرتا ہے کہ وہ قابل رسائی ہے۔ ٹریفک بھیجی جائے یا نہیں، اس کا فیصلہ صرف دوسرا کرتا ہے۔
- براؤزر کے مآخذ ایک فہرست تک محدود ہیںدوسرے مآخذ سے آنے والی درخواستیں صرف ان مآخذ سے قبول ہوتی ہیں جن کا پہلے سے اعلان ہو؛ جب تک فہرست خالی ہے، براؤزر کی ایسی درخواست رد کر دی جاتی ہے۔
- درخواست کے حجم کی حددرخواست کا متن پانچ میگابائٹ سے زیادہ نہیں ہو سکتا۔ بڑے مجموعے ایک ہی درخواست کے بجائے اپنے الگ حالت ریکارڈ کے ساتھ اجتماعی منتقلی کے کام کی صورت میں جاتے ہیں۔
- راز لاگ میں نہیں لکھے جاتےسرور کا لاگ نہ اجازت ہیڈر رکھتا ہے، نہ کوکی، نہ پاس ورڈ اور نہ قومی شناختی نمبر۔
شرح کی حد
حد ہر پتے اور ہر منٹ کے حساب سے ہے۔ طے شدہ قدر 120 درخواستیں فی منٹ ہے اور یہ تنصیب کے وقت مقرر ہوتی ہے۔ کتنا باقی ہے، یہ ہر جواب کی ہیڈروں میں بتایا جاتا ہے۔
| جواب کی ہیڈر | یہ کیا بتاتی ہے |
|---|---|
| x-ratelimit-limit | وقفے کے اندر مجموعی گنجائش۔ |
| x-ratelimit-remaining | اس وقفے میں کتنا باقی ہے۔ |
| x-ratelimit-reset | گنجائش کی تجدید تک کتنے سیکنڈ۔ |
| retry-after | دوبارہ کوشش سے پہلے کتنے سیکنڈ۔ صرف اسی جواب پر موجود ہوتا ہے جس نے درخواست رد کی ہو۔ |
حد عبور ہوتے ہی درخواست رد کر دی جاتی ہے اور جواب سیکنڈوں میں بتاتا ہے کہ کتنا انتظار کرنا ہے۔ دوبارہ کوشش اسی وقت کے بعد کی جاتی ہے، فوراً نہیں۔
خرابی کی ساخت
ہر خرابی ایک ہی لفافے میں واپس آتی ہے: مشین کے فیصلہ کرنے کے لیے ایک مختصر کوڈ خانہ، اور انسان کے پڑھنے کے لیے ایک وضاحتی خانہ۔
- errorمختصر کوڈ جس پر کلائنٹ اپنا فیصلہ کرتا ہے۔
- messageجو ہوا اس کی وضاحت۔
| حالت | کوڈ خانہ | اس کا مطلب |
|---|---|---|
| 400 | Bad Request | درخواست اسکیما سے میل نہیں کھاتی۔ وضاحت میں اس خانے کا نام آتا ہے جو غائب یا غلط ہے۔ |
| 401 | unauthenticated | کوئی درست شناخت موجود نہیں: ٹوکن بھیجا ہی نہیں گیا، یا اس کی معیاد ختم ہو چکی ہے، یا اس کی تصدیق نہیں ہوئی۔ |
| 404 | Not Found | ایسا کوئی اینڈ پوائنٹ نہیں، یا ایسا کوئی ریکارڈ نہیں۔ |
| 429 | Too Many Requests | شرح کی حد عبور ہو گئی؛ جواب بتاتا ہے کہ کتنی دیر انتظار کرنا ہے۔ |
| 5xx | internal_error | ایک غیر متوقع خرابی۔ تفصیل کلائنٹ کو نہیں دی جاتی؛ اسے سرور کے لاگ میں لکھا جاتا ہے۔ |
صفحہ بندی
فہرست لوٹانے والے اینڈ پوائنٹس وہی دو پیرامیٹر لیتے ہیں اور وہی شمار کنندے لوٹاتے ہیں، اس لیے صفحہ بندی کرنے والا کلائنٹ ہر اینڈ پوائنٹ کے لیے دوبارہ نہیں لکھا جاتا۔
- limitایک صفحہ کتنے ریکارڈ رکھے۔ کم از کم ایک، زیادہ سے زیادہ دو سو؛ مقرر نہ ہو تو پچاس۔
- offsetکتنے ریکارڈ چھوڑنے ہیں۔ صفر سے شروع ہوتا ہے۔
- totalفلٹروں پر مجموعی طور پر کتنے ریکارڈ پورے اترتے ہیں۔
- countیہ جواب دراصل کتنے ریکارڈ اٹھائے ہوئے ہے۔
جواب اپنے استعمال کردہ limit اور offset کو بھی دہراتا ہے؛ کلائنٹ اپنی جگہ اندازے سے نہیں، جواب سے پڑھتا ہے۔
ڈیٹا کا تبادلہ اور ویب ہکس
تبادلے کا طریقہ ایک ترتیب ہے، الگ پروڈکٹ نہیں: ہر رجسٹرڈ ایپلی کیشن اپنے ریکارڈ پر وہی طریقہ اٹھائے ہوئے ہے جس میں وہ کام کرتی ہے۔
| طریقہ | اس کا مطلب |
|---|---|
| یک طرفہ — باہر کی جانب | Optifora ڈیٹا شائع کرتا ہے؛ دوسرا فریق اسے پڑھتا ہے یا واقعات کی رکنیت لیتا ہے۔ |
| یک طرفہ — اندر کی جانب | دوسرا فریق ڈیٹا بھیجتا ہے؛ Optifora اس کی جانچ کر کے اسے لکھتا ہے۔ |
| دو طرفہ | دونوں فریق لکھتے ہیں؛ تصادم کا اصول پہلے سے طے ہوتا ہے۔ |
| ہینڈ شیک | ہر منتقلی ایک سیشن کھولتی ہے: پیشکش، تصدیق، منظوری، منتقلی اور رسید۔ رسید دونوں فریقوں کے پاس رہتی ہے۔ |
- واقعات باہر بھیجے جاتے ہیںویب ہک واقعے کو اس واپسی پتے پر بھیجتا ہے جس کا اعلان رجسٹرڈ ایپلی کیشن نے کیا ہو۔ جو واقعہ پہنچایا نہ جا سکے وہ قطار میں رہتا ہے اور دوبارہ بھیجا جاتا ہے؛ اسے خاموشی سے کبھی نہیں گرایا جاتا۔
- ایک ہی درخواست دو بار نہیں لکھتیلکھنے والی درخواست عدم تکرار کی ایک کلید اٹھاتی ہے۔ اسی کلید کے ساتھ آنے والی دوسری درخواست کوئی دوسرا ریکارڈ نہیں بناتی۔
- ہر کال ناپی جاتی ہےکس نے، کب، کس دائرے کے ساتھ اور کس نتیجے کے ساتھ بلایا — سب کچھ درج ہوتا ہے۔ یہی ریکارڈ خرابی کی تلاش کا بھی جواب دیتا ہے اور اس سوال کا بھی کہ یہ ڈیٹا کس نے کھینچا۔
- ہماری اپنی ایپلی کیشنیں بھی اسی دروازے سے آتی ہیںکوئی مراعات یافتہ دوسرا راستہ موجود نہیں۔ ہمارا اپنا انضمام ہی اس بات کا ثبوت ہے کہ باہر کے ڈویلپر کو کون سی سطح ملتی ہے۔
تبادلے کی تہہ کا ڈیٹا ماڈل موجود ہے؛ اس کے اینڈ پوائنٹس ابھی شائع نہیں ہوئے۔ جب ہوں گے تو یہ حصہ حوالہ دستاویز میں ان کے اندراجات سے جوڑ دیا جائے گا۔
حوالہ دستاویزات
حوالہ دستاویز ہاتھ سے نہیں لکھی جاتی؛ یہ اینڈ پوائنٹ کے اسکیموں سے تیار ہوتی ہے۔ جیسے جیسے ہر اینڈ پوائنٹ اپنا اسکیما دیتا ہے، دستاویز خود بھرتی جاتی ہے، اس لیے دستاویز اور اصل رویہ ایک دوسرے سے الگ نہیں ہو سکتے۔
- آج: زیر تیاریاسکیمے ماڈیول بہ ماڈیول آگے بڑھ رہے ہیں۔ دستاویز شائع ہونے سے پہلے ہر اینڈ پوائنٹ کی درخواست اور جواب اس میں نظر آنے لگیں گے۔
- دو شکلیں شائع کی جائیں گیایک مشین کے پڑھنے کے قابل OpenAPI دستاویز، اور اسی دستاویز سے تیار ہونے والا ایک حوالہ صفحہ جو براؤزر میں دیکھا جا سکتا ہے۔
- رسائی درجہ بہ درجہ ہےخلاصہ ہر ایک کے لیے کھلا ہے۔ مکمل حوالہ دستاویز رجسٹرڈ انٹیگریٹر کو دیے گئے دستاویزی ٹوکن کے پیچھے ہو سکتی ہے؛ پیداواری کلیدیں اور واپسی کے پتے دستاویز کا معاملہ ہیں ہی نہیں — وہ ایپلی کیشن کے ریکارڈ کا حصہ ہیں۔
- پتوں کا معیاردو حوالہ دستاویزات شائع ہوتی ہیں اور ان کے پتے طے ہیں: client-api.optifora.com/docs کھلا ہے، admin-api.optifora.com/docs اجازت مانگتا ہے اور باہر کے لیے بند ہے۔ آج ان میں سے کوئی زندہ نہیں؛ جیسے ہی ہوں گے، ان کے روابط اسی حصے میں شامل کر دیے جائیں گے۔
اگر آپ کا انضمام کا منصوبہ پہلے سے واضح ہے تو رابطہ صفحے سے ہمیں لکھیے: سطح کھلتے ہی سب سے پہلے مطلع ہونے والوں میں آپ ہوں گے۔
کیا آپ کی کوئی خاص درخواست ہے؟
یہ صفحات بتاتے ہیں کہ معاونت کا عمل کیسے چلتا ہے۔ اگر آپ کی کوئی درخواست یا سوال ہے تو رابطہ صفحے سے ہمیں لکھیں۔
رابطہ صفحے پر جائیں