ডিজাইনিং রেস্ট এপিআই [৬] : এপিআই ডকুমেন্টেশন

in ডিজাইনিং রেস্ট এপিআই,

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

 

A REST API should spend almost all of its descriptive effort in defining the media type(s) used for representing resources and driving application state.

— Roy Fielding, REST APIs must be hypertext driven

 

রেস্ট এপিআই ডকুমেন্টেশন

একটি এপিআই এর সকল রিসোর্স, ফাংশনালিটি একটি সুন্দর স্টাইলে ম্যানুয়ালি প্রেজেন্ট করতে গেলে যে পরিমান শ্রমের প্রয়োজন তার কথা চিন্তা করতে গেলে চোখে ঘুম চলে আসে । তাছাড়া যেহেতু এপিআই প্রতিনিয়ত আপডেট হবে সেহেতু পাশাপাশি আপনাকে আপনার ডকুমেন্টেশনেও ব্যাপক পরিবর্তন আনতে হতে পারে । এই বিষয়গুলো হ্যান্ড্যেল করার কিছু টুল নিয়ে এখন আমরা জানব ।

অটোমেটেড এপিআই ডকুমেন্টেশন

এমন যদি হত যে, আমি কোড করব সাথে সাথে এপিআই কনজিমারদের জন্য একটি ডকুমেন্টেশন অটোমেটিক তৈরী হয়ে যাবে ! পুরোপুরি এমন না হলেও জনপ্রিয় প্রোগ্রামিং ল্যাঙ্গুয়েজ যেমন সি++ , জাভা ইত্যাদির জন্য ডক্সিজেন, জাভাডক্স এর মত অনকে অটোমেটেড টুল আছে যা ডকুমেন্টেশন অনেক সহজ করে দিয়েছে । রেস্ট আর্কিটেকচারের জন্য অটোমেটেড কিছু টুল থাকলেও সেগুলো ব্যবহারের পূর্বে আপনাকে ভালোভাবে বুঝে শুনে করা উচিত । কারন রেস্ট এপিআই এর ডকুমেন্টেশন অন্যন্য প্রোগ্রামিং ল্যাঙ্গুয়েজ এর একটু ভিন্ন । রেস্ট এপিআই ডকুমেন্টেশন হল, রিকোয়েস্ট কোন URI তে কোন ফরম্যাটে কি প্যারামিটার দিয়ে সেন্ড করতে হবে তার একটি রিপ্রেজেন্টশন । যেহেতু রেস্ট এপিআই এর রিকোয়েস্ট ম্যাপিং এর জন্য নির্দিষ্ট কোন স্ট্যান্ডার্ড নেই সেহেতু আপনার কোড থেকে অটোমেটেড ডকুমেন্টেশন তৈরী করা অনেকটা অসম্ভব। এক্ষেত্রে দুটি সম্ভাব্য সমাধানের কথা ভেবে দেখা যেতে পারে

১। কোড থেকে ডকুমেন্টেশন জেনারেট

কোডের পাশাপাশি রেস্ট এপিআই ডকুমেন্টেশন জেনারেট করার জন্য  ভালো ফ্রেমওয়ার্ক খুব কমই আছে ।জাভাবেজড এপিআই এর জন্য Enunciate একটি ভাল উদাহরন হতে পারে।

কোড থেকে এপিআই ডকুমেন্টেশন জেনারেট করার আরেকটি সহজ উপায় হল কোডের কমেন্ট ।

/**
* @api {put} /user/:id Change a User
* @apiVersion 0.3.0
* @apiName PutUser
* @apiGroup User
* @apiPermission none
*
* @apiDescription This function has same errors like POST /user, but errors not defined again, they were included with "apiErrorStructure"
*
* @apiParam {String} name Name of the User.
*
* @apiUse CreateUserError
*/
function putUser() {
.....your api code ...
return;
}

অনেক সময় দেখা যায় আপনি এপিআই কোড পরিবর্তন করেছেন কিন্তু ডকুমেন্টেশন আপডেট করেন নি । কমেন্ট থেকে ডকুমেন্টেশন জেনারেট করলে এরকম ভুল হওয়ার সম্ভাবনা যেমন কম থাকে তেমনি আপনাকে আলাদা করে ডকুমেন্টেশনও হয়ে গেল । কোড কমেন্টকে সুন্দরভাবে ডকুমেন্টশনে প্রেজেন্ট করতে apidocjs একটি অসাধারন টুল ।

২। ওয়ান-টু-ওয়ান ম্যাপিং এর একটি ফরম্যাটেড ডাটা স্ট্রাকচার

এক্ষেত্রে আপনার রিকোয়েস্ট ম্যাপিংগুলোকে একটি নির্দিষ্ট ডাটা ফরম্যাটে সাজিয়ে একটি টুল দ্বারা প্রেজেন্ট করা হয় ।

Swagger – রেস্টফুল এপিআইকে সম্পূর্ন এবং স্মার্ট ভাবে রিপ্রেজেন্ট করার জন্য এটি একটি অসাধারন টুল । এই টুলটির আরো দুটি জনপ্রিয়ে অলটারনেট হল RAML এবং Api BluePrint

jsondoc: একটি জেসন ডকুমেন্ট থেকে এপিআই ডকুমেন্টেশন জেনারেট করতে এর জুড়ি নেই।

পূর্ববর্তী পোস্ট   »  ডিজাইনিং রেস্ট এপিআই [৫] : এপিআই ভার্সনিং


মুক্ত জ্ঞান ছড়িয়ে দিন সবার মাঝে!