با بخش سوم از اصول وب سرویس RESTful با شما همراه هستیم.در مقالات قبلی تمام آموزش های مورد نیاز برای ساخت وب سرویس restful بر اساس معماری و قوانین REST را دیدیم (وب سرویس REST چیست).
در این بخش قصد داریم به شما در مورد مستند سازی و ورژن بندی و .. به عنوان یکی از اصول پیشنهادی در طراحی API های RESTful اشاره کنیم.
مستند سازی وب سرویس RESTful
یک API خوب باید مستندات خوبی نیز داشته باشد. این مستندات باید به راحتی و برای همه برنامه نویسانی که قصد دارند از APIشما استفاده کنند قابل دستیابی باشند.
دقت داشته باشید که بیشتر برنامه نویسان پیش از آنکه از API شما استفاده کنند مستندات شما را مطالعه می کنند. بنابر این اگر مستندات شما در قالب فایل های PDF باشند و یا اینکه برای دسترسی نیاز به لاگین داشته باشند هم دسترسی به آنها دشوار می شود و
هم آنکه نمی توان با جستجو انها را به راحتی یافت. بنابراین پیشنهاد می شود آنها را در قالب هایی مانند HTML منتشر نمایید.
دقت داشته باشید که مستندات شما علاوه بر توضیحات,بهتر است مثال های کاملی از نحوه ارسال درخواست و دریافت پاسخ داشته باشد. ترجیحا طوری این مثال ها را بنویسید که بتوان آن را براحتی copy/paste کرد. اگر لینک درخواست ها نیز قابل کپی شدن باشند به
برنامه نویسانی که قصد استفاده از API شما را دارند بسیار کمک خواهد کرد.
نکته مهم دیگری که باید توجه کنید این است که هر گونه بروز رسانی در API خود را باید در مستندات بیاورید. بعنوان مثال درخواست هایی که دیگر نباید استفاده شوند یا deprecate شده اند و آخرین تغییرات در نحوه دستیابی به API باید به برنامه نویسان اطلاع داده شود.
بهتر است این کار را بصورت change log و یا mailing list انجام دهید.
ورژن بندی (Versioning)
همیشه و همیشه API خود را نسخه بندی کنید. این مسئله باعث می شود که تکامل API شما راحت تر صورت پذیرد و از به مشکل خوردن کلاینت ها در هنگام تغییرات جلوگیری نماید. شما می توانید تغییرات را براحتی در ورژن جدید اعمال کنید و اجازه دهید کلاینت های قدیمی تر با ورژن قدیمی بدون هیچ مشکلی به کار خود ادامه دهند.
اما سوال اینجاست که ورژن بهتر است در URL مشخص گردد و یا در header درخواست. نظرات مختلفی در این باره وجود دارد. اگر بخواهیم به طور آکادمیک بگوییم بهتر است ورژن در header مشخص شود. اما پیشنهاد می شود که ورژن در URL مشخص شود تا بتوان از پشتیبانی مرورگر نیز بهره مند شد.
اگر بیاد داشته باشید در ابتدای این بحث گفتیم که یکی از ویژگی های API خوب این است که بتوان از طریق نوار آدرس آن را پیمایش کرد.
روشی که در اینجا می خواهیم پیشنهاد کنیم آن است که ورژن های اصلی API را در URL مشخص کنید. اما تغییرات جزئی را بدون تغییر ورژن اصلی و با ایجاد زیر ورژن هایی در header در خواست تعیین کنید. بعنوان مثال در URL شما ورژن v1 را مشخص می کنید در
header نیز می توانید زیر ورژن های آن را مانند ۱٫۰٫۱ را تعیین نمایید که نشان دهنده تغییرات جزئی تر هستند.
هیچ API ای وجود ندارد که کاملا stable و بدون تغییر باقی بماند. بنابراین ورژن دهی به API یکی از مهمترین کارهایی است که همواره باید آن را مد نظر قرار دهید تا بتوانید مدیریت بهتری بر روی تغییرات خود داشته باشید. همواره مستندات خود را بروز نگه دارید و تغییرات
API خود را به اطلاع برنامه نویسان کلاینت ها برسانید.
فیلتر کردن
هنگامی که می خواهید نتایج را فیلتر کنید به ازای هر فیلدی که می خواهید فیلتر کنید یک پارامتر در نظر بگیرید و آن را در URL قرار دهید. به عنوان مثال فرض کنید می خواهیم لیستی از کاربران فعال را از سرور دریافت کنیم. در این صورت بهتر است URL شما بصورت
users?state=active/ باشد. در این جا state پارامتری است که بر اساس آن می خواهیم نتایج را فیلتر کنیم.
مرتب سازی
همانند آنچه در مورد فیلترینگ داشتیم، برای مرتب سازی نیز پارامتری را به URL اضافه می کنیم. معمولا این پارامتر با نام sort اضافه می شود. به عنوان مثال اگر بخواهیم کاربران را بر اساس تاریخ تولدشان مرتب کنیم پیشنهاد می شود بصورت زیر این کار انجام شود :
|
1 |
users?sort=-birth_date/ |
در مثال بالا با –birth_date مشخص می کنیم که می خواهیم نتایج را به صورت نزولی مرتب سازی کنیم. اگر بخواهیم مرتب سازی را بر اساس پارامتر های دیگر نیز انجام دهیم پیشنهاد می شود لیست پارا متر ها را با کاما از هم جدا کرده و همه را با هم در قالب پارامتر sort ارسال کنیم.
بعنوان مثال اگر بخواهیم کاربران را بر اساس نام و نام خانوادگی مرتب کنیم می توان بصورت زیر عمل نمود :
|
1 |
GET /users?sort=first_name,laste_name |
جستجو کردن
در هنگام جستجو کردن در صورتی که از جستجوی تمام متن استفاده می کنید پیشنهاد می شود پارامتری بنام q را برای مشخص کردن رشته مورد جستجو در URL اضافه نمایید.
می توان با ترکیب این سه مورد URL های پیچیده ای و در عین حال خوانایی را بصورت زیر ایجاد نمود :
|
1 2 3 4 5 |
GET /users?sort=-updated_at GET /users?state=closed&sort=-updated_at GET /users?q=return&state=open&sort=-priority,created_at |
استفاده از نام های مستعار برای برخی از پرس و جو های رایج
برخی از پرس و جو ها ممکن است بسیار رایج و مورد استفاده باشند. بد نیست برای راحتی کار استفاده کنندگان API های خود این پرس و جو ها را در قالب URL های خاصی در اختیار آنها قرار دهید. به عنوان مثال گرفتن آخرین لیست آخرین محصولات را می توانید در قالب
یک مسیر مجزا مثلا GET /products/recently_added در اختیار کاربران قرار دهید.
استفاده از SSL
همیشه و بدون هیچ استثنائی از SSL استفاده کنید. توجه داشته باشید که API شما از هر نقطه ای که دسترسی به اینترنت داشته باشند قابل دسترسی است.
بنابراین اگر داده های ارسالی و دریافتی شما رمزگذاری نشوند به راحتی قابل شنود هستند و یک تهدید امنیتی برای سیستم شما به شمار می روند.
یکی دیگر از مزایای استفاده از SSL این است که احراز هویت کلاینت ها تضمین می شود و دیگر نیاز به sign کردن API ها نیست. نکته مهم دیگر که باید مد نظر قرار دهید این است که اگر کلاینتی خواست بدونSSL به URL های API شما دسترسی پیدا کند آن را به هیچ
وجه به URL های SSL خود هدایت (redirect) نکنید. بجای این کار خطایی به او باز گردانید. بنابراین دسترسی را به URL های SSL محدود کنید.
امیدوارم با به کارگیری این اصول وب سرویس RESTful در طراحی های API بتوانید میزان توسعه پذیری , خوانایی و استفاده آسان از آن را تا حد زیادی افزایش بدید و به اصول استاندارد آن برسید .
در ادامه مقاله آموزشی اصول وب سرویس RESTful به اعمال محدودیت و نوع فرمت داده و .. می پردازیم . با ما همراه باشید .
با سلام استاد
در صورت امکان راهنمایی بفرمایید
//Input value key To send the user = value_license = xxxxxxxxxxxxxxxxx
///////////////////////////////////
$Tk_Alertlogin = $vars[‘value_license’];
$curl = curl_init( );
curl_setopt( $curl, CURLOPT_URL, ‘https://yousite.com/api/api.php’ );
curl_setopt( $curl, CURLOPT_HTTPHEADER, array( ‘Content-Type’ => ‘application/json’ ) );
curl_setopt( $curl, CURLOPT_POSTFIELDS, ‘license=’ . $reza_tntlogin . ‘&secret_key=reza_tntlogin&domain=’ . $_SERVER[‘SERVER_NAME’] );
curl_setopt( $curl, CURLOPT_TIMEOUT, 400 );
curl_setopt( $curl, CURLOPT_SSL_VERIFYPEER, false );
curl_setopt( $curl, CURLOPT_RETURNTRANSFER, true );
$result = json_decode( curl_exec( $curl ) );
curl_close( $curl );
if ($result->status == 100) {//The correct process
}else{
echo ‘ Oh, something went wrong : ‘ . $result->status . ”;
}
///////////////////////////////////
//Perfect answer for file api.php
// And returned xxxxxxxxxxxxxxxxx
سلام.
متوجه نشدم الان مشکل شما با کد چی هست.
توضیح بفرمایید تا راهنمایی بشه
سلام متشکرم از پاسخ جنابعالی
این کدها مشکلی نداره حالا میخوام هر مقداری داخل متغیر $reza_tntlogin ذخیره و ارسال بشه لطفا بفرمایید دقیقا و کامل کد های فایل api.php چطور نوشته و برگشت بشه تا فرایند انتهای این کد ها برقرار بشه