توسعه دهندگان وب به صورت مکرر در مورد اصول REST و ساختار داده RESTful صحبت می کنند زیرا یکی از جنبه های حیاتی توسعه وب مدرن است ولی بعضی اوقات این کار فوق العاده گیج کننده می شود.REST به خودی خود یک تکنولوژی نیست ولی می توان گفت روشی است برای ایجاد API هایی با اصول سازماندهی مشخص.

این اصول ،راهنمای توسعه دهندگان هستند تا بتوانند محیطی یکسان و جهانی برای پردازش درخواست های API ایجاد کنند.

در این پست می خواهم تمرین توسعه دادن RESTful را از یک نگاه کلی عقاب گونه توضیح دهم. می خواهم به جای چگونه، در مورد چرا صحبت کنم. البته مقداری وارد هر دو موضوع خواهیم شد . در کل این آموزش برای توسعه دهندگانی است که در هنوز مفهوم REST API را کامل درک نکرده اند.

REST برای توسعه دهندگان وب

REST مخفف Representational State Transfer است. این شاید به نظر گیج کننده برسد و توضیحات ویکی پدیا در این مورد شاید آن را پیچیده تر هم بکند. اما امکان ساده کردن این اصطلاح وجود دارد.

REST فقط یک سری از دستور العمل ها و سبک های معماری است که برای انتقال داده ها استفاده می شوند. این عموما در مورد اپلیکیشن های تحت وب کاربرد دارد ولی می تواند داده ها را به سایر برنامه ها نیز ارسال کند.

کلمه API نیز مخفف Application Programming Interface می باشد که به روش های اتصال به سایر کتابخانه ها و برنامه ها اطلاق می شود. ویندوز API های مختلفی دارد ، تویتتر نیز یک API وب دارد که البته کارهای مختلفی را با هدف های متفاوت از هم انجام می دهند.

اگر بخواهم جمع بندی کنم ، RESTful API ها در واقع API هایی هستند که از معماری REST تبعیت می کنند.

معماری REST دقیقا چیست ؟

اینجا جایی است که غیر فنی مطرح کردن جزئیات کمی سخت است. ما اینجا یک سری ثابت های معماری در REST داریم ، مثل :

• ثبات (Consistency) در کل ساختار API
• موجودیت مستقل (Stateless existence) . مثلا عدم وابستگی به session های سمت سرور
• استفاده از کدهای وضعیت HTTP در جای مناسب
• استفاده از نقاط پایانی URL با سلسله مراتب منطقی
• نسخه بندی (Versioning) در URL به جای درخواست HTTP

دیگر هیچ دستور العملی برای جزئیات بیش از حد مثل جزئیات HTML5 در W3C وجود ندارد که می تواند منجر به سردرگمی شود و بخاری بد بو از عدم قطعیت را در اطراف اصطلاح REST پدید آورد.

REST یک متدولوژی یا روش شناسی سبُک است که آن را برای انتقال داده های HTTP مناسب می کند. این همان علتی است که REST را در وب اینقدر محبوب کرده است و اینقدر از طرف عموم به عنوان بهترین روش پیاده سازی API شناخته می شود.

همانطور که Vinay Sahni گفته است : ” یک API ،رابط کاربری توسعه دهنده است.” همه چیز باید به راحتی قابل استفاده باشد و یک تجربه کاربری خوب را فراهم کند .هدف RESTful API ها همین است.

نکاتی مهم برای RESTful API ها

API User یک توسعه دهنده وب است که می تواند برنامه هایی برای اتصال به سرور خارجی API بنویسد و اطلاعات ضروری روی HTTP به او برگشت داده شوند. توسعه دهنده وب سپس می تواند اطلاعات را در سایت خود نمایش دهد بدون دسترسی شخصی به سرور خارجی API.

در کل از چهار دستور برای دسترسی به RESTful API  استفاده می شود :

1. GET برای گرفتن یک شی
2. POST برای ایجاد یک شی
3. PUT برای ویرایش یا بازنویسی یک شی
4. DELETE برای حذف یک شی

با هر بار فراخوانی API ،یکی از این متد ها باید به سرور پاس داده شود تا سرور بداند چطور باید رفتار کند.

اکثریت قریب به اتفاق وب API ها فقط درخواست های GET را اجازه می دهند تا بتوان داده ها را از سرور دریافت کرد. احراز هویت کاربر اختیاری است ولی شدیدا ایده خوبی است وقتی که پای متد های حساس و دارای قابلیت خرابکاری مثل PUT و DELETE درمیان باشد.

با این حال بسیاری از RESTful API ها تا این حد پیش نمی روند . Pokéapi را در نظر بگیرید که یک API رایگان برای بازی Pokémon است. این API برای عموم باز است ولی با یک نرخ محدودیت معقول و مناسب (محدودیت کاربران برای تعداد معینی از ارسال درخواست به API در یک بازه زمانی مشخص) . به علاوه این API فقط متدGET را پشتیبانی می کند.شاید این را بتوان اصطلاحا یک API مصرفی نامید.

نوع داده بازگشتی نیز مهم است و باید با همه منابع دیگر همگن و هماهنگ باشد.JSON یکی از انوع داده بازگشتی است که بسیار نیز محبوب است و جزئیات آنلاین آن نیز ساختار داده در آن را به خوبی توضیح داده است.

RESTful API ها از “اسم” برای نامگذاری اشیا و از “صفت” برای نامگذاری کارهایی که قرار است روی اشیا انجام شود استفاده می کند. اعتبارسنجی می تواند بخشی از این باشد همچنین نرخ محدودیت.ولی یک API کوچک و ساده لازم نیست نگران ایجاد محدودیت برای کاربران باشد.

دسترسی به منابع API

API های عمومی معمولا از طریق آدرس های وب سایت در دسترس هستند.این به این معنی است که ساختار آدرس (URL) مهم است و فقط بای دبرای API استفاده شود تا تداخلی بین آدرس ها نباشد.بعضی از API های می توانند برای نسخه های بروز شده خود ، یک پیشوند به آدرس اضافه کنند مثلا /v2/ . این روش برای توسعه دهندگانی است که نمی خواهد نسخه قبلی API شان منقرض شود و می خواهند در عین حال که نسخه قبلی قابل استفاده است ، به کاربران امکان استفاده از نسخه جدید را نیز بدهند.

برای اطلاعات بیشتر در این زمینه من این مطلب را دوست داشتم که در مورد ساختار ساده URL توضیحاتی داده است و چند مثال نیز از سرویس های دیگر آورده است.

دقت کنید که داده بازگشتی از طرف API می تواند به صورت کلی بوسیله متدهای HTTP تغییر یابد.برای مثال GET داده ها را دریافت کند ولی POST اطلاعات جدیدی ایجاد کند.بر همین اساس درخواست می تواند به آدرس یکسانی از API ارسال شود ولی نتیجه می تواند بسیار متفاوت باشد.

مشاهده نمونه های مشابه آنلاین ممکن است به شما برای درک بهتر مفاهیم کمک کند . ما قبلا در مورد Pokeapi صحبت کردیم ولی بعضی دیگر از نمونه API ها در دنیای واقعی هستند که می توان آنها را مطالعه کرد:

• Reddit API
• GitHub API
• Flickr API
• Pinterest API

API خودتان را بسازید

مراحل ایجاد یک API برای خودتان نمی تواند خیلی راحت باشد ولی آنقدر ها هم که فکر می کنید سخت و پیچیده نیست. فقط نیاز به آشنایی با الگوهای طراحی API و انتخاب بهترین روش ها دارید تا چیزی را بسازید که ارزش واقعی داشته باشد. هر API باید به سرور شما وصل شود تا داده ها را برگشت دهد. شما نه تنها نیاز به کدنویسی برای انجام این کار دارید بلکه باید داده های برگشتی را فرمت دهی کنید (مثلا به JSON). دیگر نیازمندی های بالقوه شامل اعتبارسنجی (Authentication) و اعمال محدودیت های مختلف برای امنیت و پایداری بیشتر می شود . همانطور که می بینید این کار کار یک قلب ضعیف نیست !

اما اجازه دهید به برخی از اصول ساده معماری API ها نگاهی بیندازیم .

نقاط پایانی کار را ایجاد کنید

یکی از جنبه های ایجاد API ایجاد نقاط پایانی در ساختار URL است . وقتی دارید منابع (Resources) را ایجاد کنید نیاز دارید تا از اسم استفاده کنید نه از صفت. این به این معنی است که داده های API باید به صورت شخص, مکان و یا چیزی برگشت داده شوند. اغلب هم چیزی با خصیصه های معین (مثلا یک توییت با همه متادیتا هایش).

یادگیری اسم گذاری مثل روش فوق شاید سخت باشد ولی یکی از جنبه های حیاتی طراحی API هاست.ساده سازی هر زمانی که ممکن باشد بهترین راه است .

یکی از نقاط بحث برانگیز استفاده از اسم های مفرد یا اسم های جمع است.مثلا اگر شما در حال طراحی API برای Twitter باشید می توانید یکی از دو راه زیر را در نظر بگیرید:

$ /tweet/15032934882934
$ /tweets/15032934882934

در این مورد به نظرم اسم مفرد بهتر است .مخصوصا وقتی یک منبع قرار است برگشت داده شود(توییت). ولی جواب ۱۰۰٪ قطعی و مستندسازی شده ای برای این سوال وجود ندارد و بهتر شما با توجه به پروژه خودتان بهترین را انتخاب کنید.

تنظیم نوع داده برگشتی

موردی دیگری که توجه خاصی می طلبد نوع داده برگشتی از API است.خیلی از کاربران وب از API انتظار دریافت داده از نوع JSON را دارند پس این بهترین گزینه می تواند باشد.XML یکی از گزینه های دیگر است اگر می خواهید هر دو را در اختیار کاربران قرار دهید.با این حال اساسی ترین گزینه همان JSON است که صحبتش را کردیم .

جزپیات زیادی در مورد طراحی API ها وجود دارد . من پیشنهاد می کنم شما ابتدا با API های دیگر مثل Instagram,Twitter, Linkedin و … بازی کنید تا ببینید دیگر توسعه دهندگان چگونه API هایشان را می سازند و اینگونه با روش های مرسوم این حوزه بیشتر آشنا خواهید شد.

اگر می خواهید شروع کنید می توانید از این منابع استفاده و کدهایش را تغییر دهید :

• REST API Tutorial Site
• Writing a Simple REST API
• Building a RESTful Web Service

منابع بیشتر

بهترین راه برای یادگیری وب فقط تمرین است ولی بهترین محل برای شروع توسعه دادن API اتصال به API های دیگر است . منابع زیر نیز می توانند به شما در این راه کمک کنند:

کتاب ها

• REST API Design Rulebook
• RESTful Web APIs
• RESTful Web Services Cookbook
• Undisturbed REST: A Guide to Designing the Perfect API

مقالات

• A Beginner’s Guide to HTTP and REST
• Creating a RESTful API
• RESTful Resource Naming Guide
• Creating A REST API using the MEAN Stack

منبع