আমি স্পষ্ট API ডকুমেন্টেশন লিখব যা আপনার ডেভেলপাররা প্রথম দিন থেকেই অনুসরণ করতে পারবে

কেন বেশিরভাগ API ডক্স ব্যর্থ হয়

তারা এন্ডপয়েন্টগুলি বর্ণনা করে এবং যে অংশগুলি আসলে লোকেদের থামিয়ে দেয় তা বাদ দেয়: কীভাবে প্রমাণীকরণ করতে হয়, একটি বাস্তবসম্মত অনুরোধ কেমন দেখায়, ত্রুটির অর্থ কী এবং এটি সম্পর্কে কী করতে হবে। পাঠক তখন একটি সমর্থন টিকিট খোলে, যা ডকুমেন্টেশন সরানোর জন্য বিদ্যমান।

আমি কিভাবে এটি লিখি

স্মৃতি থেকে নয়, উৎস থেকে। আমি রুট, বৈধতা স্তর এবং ত্রুটি হ্যান্ডলারগুলি পড়ি, তারপর বাস্তব শংসাপত্র দিয়ে নিজেই API কল করি। ডকুমেন্টেশনের প্রতিটি উদাহরণ একটি অনুরোধ যা আমি করেছি এবং একটি প্রতিক্রিয়া যা আমি পেয়েছি — কোনো উদ্ভাবিত পেলোড নেই, কোনো স্ট্যাটাস কোড নেই যা এন্ডপয়েন্ট কখনও ফেরত দেয় না।

ডকুমেন্টেশনে কী থাকে

• প্রমাণীকরণ: একটি টোকেন প্রাপ্ত করা, এটি রিফ্রেশ করা এবং সেশনের মাঝখানে এর মেয়াদ শেষ হলে কী ঘটে।
• প্যারামিটার সহ প্রতিটি এন্ডপয়েন্ট, একটি সম্পূর্ণ উদাহরণ অনুরোধ এবং বাস্তব প্রতিক্রিয়া আকার।
• একটি ত্রুটি রেফারেন্স যা প্রতিটি ত্রুটি কোডকে একটি কারণ এবং একটি ফিক্সের সাথে ম্যাপ করে, কেবল বার্তাটি পুনরাবৃত্তি না করে।
• একটি শুরু করার পথ যা একজন নতুন ডেভেলপারকে শূন্য থেকে দশ মিনিটের মধ্যে একটি সফল কলে নিয়ে যায়।
• রেট সীমা, পেজিনেশন, ওয়েবহুক এবং আইডম্পোটেন্সি যেখানে তারা আসলে প্রযোজ্য সেখানে ব্যাখ্যা করা হয়েছে।

বিন্যাস

আপনার রিপোজিটরিতে মার্কডাউন, OpenAPI বা একটি ডক্স সাইটের জন্য কাঠামোগত — যেটি আপনি আসলে বজায় রাখবেন। আপনার ব্যবহারকারীরা যে ভাষাগুলি সম্পর্কে জিজ্ঞাসা করে সেগুলিতে কোড নমুনা, সেগুলি চালিয়ে যাচাই করা হয়েছে। আপনি চাইলে পোস্টম্যান বা অনুরূপ সংগ্রহ অন্তর্ভুক্ত।

আমার কি দরকার

রিপোজিটরি অ্যাক্সেস বা OpenAPI ফাইল, একটি পরীক্ষা পরিবেশের জন্য একটি কার্যকরী শংসাপত্র এবং আপনার সহায়তা দল যে প্রশ্নগুলির উত্তর দিতে ক্লান্ত সেগুলি। এই প্রশ্নগুলিই রূপরেখা।

অন্তর্ভুক্ত নয়

মার্কেটিং কপি। এটি সফ্টওয়্যারটি কী করে তা সঠিকভাবে নথিভুক্ত করে; ল্যান্ডিং পৃষ্ঠাটি একটি ভিন্ন শিল্প।

টার্নঅ্যারাউন্ড এবং যোগাযোগ

একটি প্রথম সম্পূর্ণ খসড়া সাধারণত এক সপ্তাহের মধ্যে আসে এবং আপনি আপনার নিজস্ব সহায়তা দল যে প্রশ্নগুলির উত্তর দিতে থাকে তার বিরুদ্ধে এটি পর্যালোচনা করেন। আমি ভুল কিছু পালিশ করে বিতরণ করার চেয়ে বরং যে প্রকৌশলী প্রান্তিক কেসগুলি জানেন তার দ্বারা তাড়াতাড়ি সংশোধন করা পছন্দ করি। চূড়ান্ত নথির প্রতিটি উদাহরণ আপনার API এর বিরুদ্ধে কার্যকর করা হয়েছে, তাই এতে কিছুই উচ্চাকাঙ্ক্ষী নয়।