اصولا در معماری یک سرویس RESTful یکسری node کلاینت و سرور داریم که میخواهند با استفاده از پروتک HTTP باهم تعامل داشته باشند و برای ایجاد این تعامل یکسری عملیات تعریف میشود که با توجه به پروتکل ارتباطی HTTP روی یکسری URL این عملیات تعاملی پیاده سازی شده اند و در این بخش نگاهی خواهیم انداخت به اجزا و چگونگی کارکرد سرویس
نگاهی بکنیم به ساختار RESTful api :
RESTful API یکسری اجزا دارد مانند :
Resource ها : به مجموع مدل ها و متد هایی که عملیاتی روی مدل ها انجام میدهند resource میگوییم
Collection ها : به مجموع Resource ها Collection گفته میشود مثلا یک مدرسه شامل دانش آموزان ، معلمان ، دروس و... هستند
URL : به آدرسی که Resource ها در آن آدرس قابل دستیابی باشند و برخی عملیات روی آن بتوانیم تعریف کنیم
API endpoint چیست ؟
در طراحی در نگاه اول، برای هر عملیاتی یک URL ست میکنیم که در سرویس بتوانیم عملیات را از هم تفکیک کنیم حال عملیات ممکن است شامل اضافه کردن اطلاعات، پاک کردن یا بروز کردن آن و... باشد
اگر قرار باشد برای هر عملیاتی یک URL ست کنیم مدیریت و Maintenance کردن سرویس در آینده اگر تغییرات جزیی را بخواهیم اعمال کنیم نیاز به حجم زیادی از کدنویسی هستیم چون برای تک تک عملیاتی که با یک نوع دیتا سروکار دارند باید تک تک آن تغییرات اعمال شود
اینجا Best Practice ارائه شده روی سرویس استفاده از متد های HTTP مانند PUT , GET و ... است که به آنها verb میگوییم
با کمک Verb ها روی یک URL میتوانیم یکسری عملیات در سطح ریسورس داشته باشیم اینجا از متد های HTTP مانند (PUT, DELETE , GET , POST و ... ) استفاده میکنیم مثلا برای ایجاد یک رکورد جدید از PUT و برای دریافت آن از GET استفاده میکنیم
هنگامی که میخواهیم در طراحی endpoint ها نامگذاری کنیم شاید به این نکته رسیده باشید که اگر endpoint ای قرار است لیست دانش آموزان را برگرداند به چیزی شبیه به getAllStudents/ برسیم ولی این یک اشتباه در طراحی است چرا که طبق استاندارد تعریف شده در Unified Resource Locator یا همان URL باید نام تنها، اشاره به ریسورس نماید و نباید معرف عملیات باشد
و راه اصولی این است که یک URL مثلا با نام students/ داشته باشیم و با verb ها عملیات را پوشش دهیم مثلا با GET لیست student ها را دریافت کنیم
بیاییم با برخی از verb های پر کاربرد در طراجی RESTful آشنا شویم :
GET : میتواند از ریسورس اطلاعات خواسته شده را دریافت کند
POST : میتواند اطلاعات یک ریسورس را ذخیره کند
PUT : از این متد برای ویرایس اطلاعات ریسورس میتوان استفاده کرد
DELETE : برای حذف اطلاعات ریسورس استفاده میشود
خب تا اینجا با نحوه کارکرد ریسورس ها ، endpoint ها , verb ها آشنا شدیم بیاییم ببنیم چطور میتوان نتیجه عملیاتی که درخواست کرده ایم را متوجه بشیم ؟ بعد از عملیات باید حتما متوجه شد که عملیات موفقیت امیز بوده یا نه و اگر نبوده علت آن چه چیزی بوده تا نسبت به برطرف کردن آن تلاش کنیم
برای این منظور در جواب عملیاتی که کلاینت درخواست داده ما یکسری کد وضعیت Http Status Code خواهیم داشت که هر کد معرف وضعیت عملیات خواهد بود که در ادامه با بررسی آنها میپردازیم :
هنگامی که عملیات با موفقیت روبرو بوده کد وضعیت ها با 2 شروع میشوند :
OK 200 : کد وضعیت عمومی برای نمایش موفقیت آمیز بودن عملیات ویرایش ، ایجاد و دریافت (GET , POST , PUT)
Created 201 : به طور خاص برای حالتی که اطلاعات یک ریسورس ذخیره شد از این کد استفاده میشود (POST)
204 No Content : وقتی میخواهیم یک ریسورس را پاک کنیم چون در جواب اطلاعات خاصی نیاز نداریم ارسال کنیم از این کد وضعیت استفاده میشود (DELETE) ولی اگر ریسورسی که میخواستیم حذف کنیم از قبل پاک شده بود و یا کلا موجود نبود با کد های Error مواجهه میشویم که در بخش بعدی به آنها میپردازیم
کد وضعیت Error ها که با 4 شروع میشوند و نشانگر ناموفق بودن عملیات است :
Bad Request 400 : کلاینت درخواستی ارسال کرده که برای سرور قابل فهم نبوده
Unauthorized 401 : درخواست کلاینت قبل از ارسال نیاز بوده که کلاینت احراز هویت کند و همچنین مجاز به اجرای آن عملیات باشد
Forbidden 403 : درخواست کلاینت درست دریافت شده اما ریسورسی که درخواست کرده قابل او ( شاید نسبت به شرایط ) مجاز نبوده
Not Found 404 : ریسورسی که درخواست شده در سرویس موجود نبوده
Gone 410 : درخواست کلاینت برای ریسورس قبلا معتبر بوده اما مکان ریسورس در حال حاضر تغییر کرده و برای این درخواست قابل دسترس نیست
کد وضعیت 3 :
Not Modified 304 : این کد وضعیت نشان میدهد که ریسورس درخواست شده چون قبلا در کلاینت کش شده و مقدار آن دقیقا برابر همان ریسورسی است که در سرور موجود است پس نیازی نبوده که سربار مجدد روی سرویس ایجاد کند و از همان ریسورس کش شده استفاده کرده است
کد وضعیت 5 برای Error های سرور که خارج از کنترل بوده :
Internal Server Error 500 : درخواست ارسالی کلاینت به علت ایجاد خطا حین عملیات داخلی سرور قادر به تولید جواب نشده و قابل دریافت نیست
Service Unavailable 503 : این کد وضعیت را بیشتر زمانی خواهیم دید که سرویس در حال تغییرات داخلی یا به دلایل دیگر موقتا سرویس در دسترس نیست
یکی دیگر از مسایل مهم در سرویس قرار دادن شماره نسخه سرویس است فرض کنید شما طی زمان سرویس را بروز کردید و هم کلاینت جدید دارید و هم قدیمی و هر دو باید بتوانند استفاده کنند و یا حتی برای یک دسته از کلاینت ها ورژن خاصی از سرویس را میخواهید ارائه دهید اینجا با ورژن بندی میتوان به هدف رسید و در URL میتوان آنرا مشخص کرد، مهمترین ویژگی که ورژن بندی ارائه میدهد جلوگیری از تداخل بین گروه کلاینت ها است و همچنین عیب یابی و توسعه را نیز ساده تر خواهد کرد
https://gateway.service.com/v1.0.3/payment/3141134