مقالات

API چیست؟

API مجموعه ای است از تعاریف و پروتکل ها برای ساخت و یکپارچه سازی نرم افزارهای کاربردی است .

API گاهی اوقات به عنوان قراردادی بین یک سرویس دهنده و یک سرویس گیرنده استفاده می‌شود . در این حالت محتوای مورد نیاز سرویس گیرنده را ( درخواست ) و محتوای تولید شده توسط سرویس دهنده (پاسخ) نامیده میشود. به عنوان مثال، طراح API برای یک سرویس هواشناسی می‌تواند مشخص کند که کاربر به عنوان سرویس گیرنده یک کد پستی ارائه کند و سرویس دهنده یک پاسخ 2 قسمتی شامل  درجه حرارت بالا و درجه حرارت پایین را به سرویس گیرنده ارائه نماید.

به عبارت دیگر، اگر می‌خواهید با یک کامپیوتر یا سیستم برای بازیابی اطلاعات یا انجام یک عملکرد تعامل داشته باشید، یک API به شما کمک می‌کند آنچه را که می‌خواهید به آن سیستم منتقل کنید تا بتواند درخواست را بفهمد و انجام دهد.

شما می توانید یک API را به عنوان یک واسطه بین کاربران یا مشتریان و منابع یا سرویس های وب که می خواهند خدمات دریافت کنند، در نظر بگیرید. همچنین راهی برای یک سازمان برای به اشتراک گذاشتن منابع و اطلاعات با حفظ امنیت، کنترل و احراز هویت و از همه مهم تر تعیین اینکه چه کسی به چه چیزی دسترسی دارد.

یکی دیگر از مزایای API این است که شما نیازی به دانستن ویژگی های حافظه پنهان ندارید و هیچ اهمیتی ندارد که منبع شما چگونه بازیابی می شود یا از کجا آمده است.
 

REST چیست ؟

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

هنگامی که درخواست سرویس گیرنده از طریق یک API RESTful انجام می شود، اطلاعاتی از وضعیت منابع را به درخواست کننده یا نقطه پایانی منتقل می کند. این اطلاعات ممکن است در فرمت های مختلفی که از طریق HTTP پشتیبانی میشود ارائه گردند. JSON عموماً محبوب‌ ترین فرمت فایلی است که می‌توان از آن استفاده کرد، زیرا هم برای انسان و هم برای ماشین‌ها قابل خواندن است.

نکته دیگری که بسیار مهم است ، اطلاعات موجود در Header هنگام صدا زدن صفحات به روش HTTP یا HTTP API RESTful است، زیرا حاوی اطلاعات شناسه مهمی در مورد فراداده درخواست، مجوز، شناسه منبع یکسان ( URI)، حافظه پنهان، کوکی‌ها و … هستند. 

برای اینکه بتوانیم یک API را  RESTful در نظر بگیریم ، باید با این معیارهای زیر مطابقت داشته باشد:

* معماری یک سرویس کلاینت، سرور که از ممکن است از یک یا چند سرویس گیرنده و سرویس دهنده تشکیل شده باشد از طریق HTTP مدیریت می شود.
 

* هیچ ارتباطی بین کلاینت و سرور وجود ندارد. در این حالت درخواست های سرویس گیرنده در سرویس دهنده نگهداری نمیشود و هر درخواست به صورت جداگانه بررسی شده و به آن پاسخ داده می شود.
 

* داده های قابل ذخیره سازی ( Cacheable ) در سرور برای پاسخگویی به درخواست های مشابه نگهداری میشود و باعث ساده تر شدن پاسخگویی به درخواست های مشابه می گردد.
 

* سیستم باید به صورت چند لایه طراحی شود تا بتوان هر نوع سرور را سازماندهی کرد. برای مثال لایه های امنیت ،   الگوریتم تعادل بار و غیره… این لایه ها نهایتا باعث ارائه سرویس به صورت سلسله مراتبی به سرویس گیرنده می شوند در حالی که این لایه ها از نظر سرویس گیرنده مخفی هستند.
 

* سرویس باید قابلیت این را داشته باشد که در صورت درخواست سرویس گیرنده بتواند کد اجرایی از سرور به سرویس گیرنده ارسال کند.

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

در مقابل، REST مجموعه‌ای از دستورالعمل‌ها است که می‌تواند در صورت نیاز پیاده‌سازی شود و API‌های REST را سریع‌تر و سبک‌تر کند
 

API های REST شما را قادر می سازند تا انواع برنامه های کاربردی وب را با تمام عملیات های ممکن CRUD (ایجاد، بازیابی، به روز رسانی، حذف) توسعه دهید.

بر اساس دستورالعمل‌ های REST پیشنهاد می‌شود که برای هر نوع خاص از تماس با سرور از روش HTTP خاص آن استفاده کنید . اگرچه از نظر فنی امکان 

نقض این دستورالعمل وجود دارد، اما به هیچ وجه پیشنهاد نمیشود.

با استفاده از اطلاعات داده شده در زیر ، روش HTTP مناسب را برای عملکرد انجام شده توسط API انتخاب کنید.

* HTTP GET
* HTTP POST
* HTTP PUT
* HTTP DELETE
* HTTP PATCH
 

1 - HTTP GET

از درخواست‌های GET فقط برای دریافت اطلاعات استفاده کنید - و به هیچ وجه برای عملیات هایی که اطلاعات را تغییر میدهد استفاده نکنید. اگر این استاندارد رعایت شود و درخواست‌های GET وضعیت اطلاعات را تغییر نمی‌دهند، این روش‌ کاملا امن است.

علاوه بر این، API های GET باید فاقد قدرت تغییر اطلاعات باشند. اگر چنین درخواستی با متد GET بارها تکرار شود باید به یک نتیجه یکسان برسد تا زمانی که API دیگری با متد (POST یا PUT) وضعیت منبع این سرویس را تغییر دهد .

اگر Request-URI به یک فرآیند تولید داده اشاره دارد، داده های تولید شده باید به عنوان موجودیت ( Entity ) در پاسخ برگردانده شود. برای مثال در قالب JSON و نباید به صورت یک متن در خروجی فرآیند نمایش داده شود.

1.1. کدهای خروجی HTTP GET

در صورتی که یک HTTP GET API را درخواست کنیم و این منبع در سرور یافت شود، باید کد پاسخ HTTP 200 OK را - همراه با بدنه پاسخ، که معمولاً محتوای XML یا JSON است (به دلیل ماهیت مستقل از پلتفرم) برگرداند.

در صورتی که منبع در سرور یافت نشد، API باید کد پاسخ HTTP 404 را برگرداند (NOT FOUND).

به طور مشابه، اگر مشخص شود که خود درخواست GET به درستی ایجاد نشده است، سرور کد پاسخ HTTP 400 (درخواست بد) را برمی گرداند.

1.2.  مثال هایی از آدرس های این متد
 

2. HTTP POST

از API های POST برای ایجاد مطالب جدید استفاده کنید، به عنوان مثال، آپلود یک فایل جدید داخل یک دایرکتوری یا یک مطلب جدید در یک جدول از پایگاه داده است.

هنگامی که به طور دقیق در مورد REST صحبت می شود، از روش های POST برای ایجاد یک مطلب جدید در مجموعه منابع استفاده می شود.

لطفاً توجه داشته باشید که POST هم قدرت ثبت اطلاعات جدید را دارد و هم به تنهایی ایمن نیست ، فراخوانی دو درخواست POST یکسان منجر به ایجاد دو مطلب متفاوت حاوی اطلاعات یکسان می‌شود (به جز شناسه منابع).

2.1. کدهای خروجی POST API

در حالت ایده‌آل، اگر اطلاعات در سرور مبدا ایجاد شده باشد، پاسخ باید کد HTTP 201 (ایجاد شده) باشد و حاوی موجودی ( Entity ) باشد که وضعیت درخواست را توصیف می‌کند و به مطلب جدید اشاره می‌کند.

اغلب اوقات، عمل انجام شده توسط روش POST ممکن است منجر به مطلبی نشود که توسط یک URI قابل شناسایی باشد. در این حالت ، کد پاسخ HTTP 200 OK یا 204 (بدون محتوا) پاسخ مناسبی است.

2.2.  مثال هایی از آدرس های این متد

3. HTTP PUT

از PUT API ها در درجه اول برای به روز رسانی یک منبع موجود استفاده کنید (اگر منبع وجود نداشته باشد، ممکن است API تصمیم بگیرد که یک منبع جدید ایجاد کند).

اگر درخواست از یک حافظه cache استفاده میکند و آدرس درخواست یک یا چند موجودیت cache شده را شناسایی کند، آن اطلاعات باید به عنوان اطلاعات  قدیمی تلقی شوند. وقتی یک API به روش PUT صدا زده میشود ، پاسخ آن قابل ذخیره سازی نیست.

3.2.   مثال هایی از آدرس های این متد

تفاوت بین API های POST و PUT را می توان در URI های درخواست مشاهده کرد. درخواست‌های POST بر روی مجموعه‌های منابع ساخته می‌شوند، در حالی که درخواست‌های PUT روی یک منبع انجام می‌شوند.

4. HTTP DELETE

همانطور که از نام این متد مشخص است، API های DELETE منابع را حذف می کنند (که توسط Request-URI شناسایی می شوند).

عملیات DELETE فاقد قدرت بروزرسانی است. اگر منبعی را حذف کنید، به طور کامل از مجموعه منابع حذف می شود.

با توجه به اینکه این متد قابلیت بروزرسانی ندارد،  برخی ممکن است استدلال کنند که این روش غیرقابل استفاده است. این یک بحث و نظر شخصی است.
اگر درخواست از یک حافظه cache استفاده میکند و آدرس درخواست یک یا چند موجودیت cache شده را شناسایی کند، آن اطلاعات باید به عنوان اطلاعات  قدیمی تلقی شوند. وقتی یک API به روش PUT صدا زده میشود ، پاسخ آن قابل ذخیره سازی نیست.

4.1. کدهای خروجی DELETE API

پاسخ موفقیت‌ آمیز درخواست‌های DELETE باید کد پاسخ HTTP 200 OK باشد. اگر پاسخ شامل موجودیتی از اطلاعات باشد.

اگر عمل حذف در صف قرار گرفته باشد، وضعیت باید 202 (پذیرفته شده) باشد. این به کاربر اعلام میکند که درخواست شما دریافت شده ولی هنوز اجرا نشده است و در صف قرار گرفته.

اگر عمل انجام شده باشد اما پاسخ شامل موجودیت نباشد، وضعیت باید 204 (بدون محتوا) باشد.

فراخوانی مکرر DELETE API در آن منبع، نتیجه را تغییر نمی‌دهد – با این حال، فراخوانی DELETE در یک منبع برای بار دوم، 404 (یافت نشد) را برمی‌گرداند زیرا قبلاً حذف شده است.

4.2.   مثال هایی از آدرس های این متد

5. واژه نامه

5.1. روش های ایمن

روش های درخواست در صورتی ایمن در نظر گرفته می شوند که مفهوم تعریف شده آنها اساساً فقط خواندنی باشد. کلاینت نمیتواند هیچ گونه تغییر حالتی را در سرور مبدا ایجاد کند.

روش های GET، HEAD، OPTIONS و TRACE روش های ایمن در نظر گرفته می شوند. طبق مشخصات HTTP، روش‌های GET و HEAD باید فقط برای بازیابی منابع استفاده شوند و آنها منبع را روی سرور به‌روزرسانی یا حذف نمی‌کنند.

هدف از تمایز بین روش‌های ایمن و ناایمن، اجازه دادن به فرآیندهای بازیابی خودکار ( spiders ) و بهینه‌سازی عملکرد حافظه پنهان ( pre-fetching ) بدون ترس از ایجاد آسیب است.

روش‌های ایمن به عوامل کاربر اجازه می‌دهند تا روش‌های دیگری مانند POST، PUT و DELETE را به روشی منحصربفرد نشان دهند تا کاربر از این واقعیت آگاه شود که یک اقدام احتمالاً ناامن در حال درخواست است و می‌توانند منبع را به‌روزرسانی یا حذف کنند. بنابراین باید با دقت بیشتری استفاده شود.