Optifora API কীভাবে কাজ করে
এই পাতাটি API-এর গঠন বর্ণনা করে: পরিচয় কীভাবে প্রমাণ করা হয়, সংস্করণ কীভাবে এগোয়, একটি অনুরোধ কোন সীমার ভেতরে থাকে, ত্রুটি দেখতে কেমন, এবং বাইরের জগতের সঙ্গে ডেটা কীভাবে বিনিময় হয়।
পণ্যটি উন্নয়নাধীন এবং API পৃষ্ঠতল এখনও সম্পূর্ণ হচ্ছে। এন্ডপয়েন্টগুলোর জন্য একটি রেফারেন্স নথি আলাদাভাবে প্রকাশ করা হবে; এই পাতায় কোনো ঠিকানা বা নমুনা কল নেই, কেবল কার্যপ্রণালি আছে।
পরিচয় যাচাই
প্রতিটি অনুরোধ হয় কোনো ব্যক্তির, নয়তো নিবন্ধিত কোনো অ্যাপ্লিকেশনের। পরিচয়হীন যে অনুরোধ সুরক্ষিত এন্ডপয়েন্টে পৌঁছায়, তা পরিচয়-যাচাই ব্যর্থ হিসেবে ফিরে আসে।
- Bearer টোকেনঅ্যাক্সেস টোকেন অনুরোধের authorization শিরোনামে বাহিত হয়। এটি স্বাক্ষরিত এবং কেবল এটুকুই জানায় যে অনুরোধটি কার।
- স্বল্প আয়ুঅ্যাক্সেস টোকেন কয়েক মিনিটের মধ্যেই মেয়াদোত্তীর্ণ হয়; এই সময়কাল স্থাপনার একটি সেটিং, যার পূর্বনির্ধারিত মান ত্রিশ মিনিট।
- নবায়ন ও আবর্তনসেশন দীর্ঘায়িত করা হয় রিফ্রেশ টোকেন দিয়ে, এবং প্রতিবার দীর্ঘায়িত করার সময় নতুন একটি জোড়া দেওয়া হয়। ব্যবহৃত হয়ে যাওয়া একটি রিফ্রেশ টোকেন দ্বিতীয়বার উপস্থাপন করা হলে ওই ব্যক্তির সব সেশন বাতিল করা হয়।
- অনুমতি টোকেনের ভেতরে গাঁথা থাকে নাটোকেন কেবল পরিচয় বহন করে; কোন ব্যক্তি কী দেখতে পাবেন তা প্রতিটি অনুরোধেই ডেটাবেস থেকে জেনে নেওয়া হয়। তাই প্রত্যাহার করা কোনো অনুমতি হাতে থাকা টোকেনের মেয়াদ শেষ হওয়ার আগেই কাজ করা বন্ধ করে দেয়।
- ইন্টিগ্রেটর কীনিবন্ধিত প্রতিটি অ্যাপ্লিকেশন নিজস্ব কী দিয়ে সংযুক্ত হয়। কী-এর মূল মানটি কেবল একবার, তৈরির সময়ে দেখানো হয়; সংরক্ষিত থাকে তার সংক্ষিপ্তসার এবং কী শনাক্ত করার জন্য ব্যবহৃত গোপন-নয় এমন উপসর্গটি।
- প্রবেশাধিকার দেয় প্রতিষ্ঠানএকটি অ্যাপ্লিকেশন যত ব্যাপকভাবেই ব্যবহৃত হোক, প্রতিষ্ঠানের দেওয়া অনুমোদন নথিভুক্ত না থাকলে সেটি একটি সারিও দেখতে পায় না। অনুমোদনটি তারিখযুক্ত, সীমা-নির্দিষ্ট এবং প্রত্যাহারযোগ্য।
সংস্করণ ব্যবস্থাপনা
- সংস্করণ থাকে পথের ভেতরেএন্ডপয়েন্টগুলো একটি সংস্করণ উপসর্গের পেছনে প্রকাশিত হয়; আজকের পৃষ্ঠতল সংস্করণ 1।
- ভাঙন সৃষ্টিকারী পরিবর্তনে নতুন পথ খোলা হয়চালু কোনো এন্ডপয়েন্টের চুক্তি জায়গায় বসেই ভাঙা হয় না। অসামঞ্জস্যপূর্ণ পরিবর্তন নতুন একটি সংস্করণ-পথে প্রকাশ করা হয়, আর পুরনোটি কাজ করতে থাকে।
- নথি নিজের সংস্করণ নিজেই জানায়রেফারেন্সে সেই সংস্করণ নম্বরটি লেখা থাকে যা থেকে এটি তৈরি হয়েছে; আপনি কোন সংস্করণ পড়ছেন তার উত্তর নথিটিই দেয়।
পরিবেশ ও সীমা
রেফারেন্সে দুটি পরিবেশ ঘোষণা করা হয়েছে: উৎপাদন এবং স্থানীয় উন্নয়ন। মূল ঠিকানাটি ইন্টিগ্রেটরকে তার কী-এর সঙ্গে দেওয়া হয়; এই পাতায় তা প্রকাশ করা হয় না।
- সচলতা ও প্রস্তুতি আলাদাভাবে মাপা হয়একটি এন্ডপয়েন্ট জানায় প্রক্রিয়াটি চালু আছে; দ্বিতীয়টি ডেটাবেসে সত্যিকারের একটি জিজ্ঞাসা পাঠিয়ে নিশ্চিত করে যে সেটিতে পৌঁছানো যাচ্ছে। ট্র্যাফিক পাঠানো হবে কি না, তা কেবল দ্বিতীয়টিই ঠিক করে।
- ব্রাউজারের উৎস তালিকা দিয়ে সীমিতভিন্ন উৎস থেকে আসা অনুরোধ কেবল আগে থেকে ঘোষিত উৎসগুলো থেকেই গ্রহণ করা হয়; তালিকাটি খালি থাকা অবস্থায় ব্রাউজার থেকে আসা ভিন্ন-উৎসের অনুরোধ প্রত্যাখ্যাত হয়।
- মূল অংশের সীমাঅনুরোধের মূল অংশ পাঁচ মেগাবাইটের বেশি হতে পারে না। বড় সংগ্রহ একক অনুরোধ হিসেবে নয়, নিজস্ব অবস্থা-রেকর্ডসহ একটি সমষ্টিগত স্থানান্তর কাজ হিসেবে যায়।
- গোপন তথ্য লগে লেখা হয় নাসার্ভার লগে কোনো authorization শিরোনাম, কুকি, পাসওয়ার্ড কিংবা জাতীয় পরিচয় নম্বর রাখা হয় না।
হার সীমা
সীমাটি প্রতি ঠিকানা ও প্রতি মিনিট হিসেবে গণনা করা হয়। পূর্বনির্ধারিত মান মিনিটে 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-এ অনুমোদন লাগে এবং তা বাইরের জন্য বন্ধ। আজ কোনোটিই সচল নয়; সচল হলে এই অংশে লিঙ্ক যুক্ত করা হবে।
আপনার ইন্টিগ্রেশন পরিকল্পনা যদি ইতিমধ্যেই স্পষ্ট হয়, যোগাযোগ পাতা থেকে আমাদের লিখুন: পৃষ্ঠতল উন্মুক্ত হলে প্রথম যাঁদের জানানো হবে, আপনি তাঁদের মধ্যে থাকবেন।
আপনার কি নির্দিষ্ট কোনো অনুরোধ আছে?
এই পাতাগুলো ব্যাখ্যা করে সহায়তার প্রক্রিয়াটি কীভাবে চলে। আপনার কোনো অনুরোধ বা প্রশ্ন থাকলে যোগাযোগ পাতা থেকে আমাদের লিখুন।
যোগাযোগ পাতায় যান