اصول طراحی و بهترین راهکارها RESTful API

اصول طراحی و بهترین راهکارها RESTful API

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

نحوه درست طراحی یک API یک جر و بحث قدیمی در فضای وب است، و یکی از بزرگترین آنهاست، چون هیچ دستورالعمل رسمی ای برای آن وجود ندارد.

ـ API رابطی است که دولوپر های زیادی از طریق آن به تبادل داده ها میپردازند. یک API خوب همیشه استفاده ساده ای دارد و زندگی دولوپر ها را راحت‌تر می‌کند. API یک محیط گرافیکی (GUI) برای دولوپر هاست،‌ اگر گیج کننده باشد آنها دنبال یک جایگزین برای آن خواهند گشت و دیگر از آن استفاده نمی‌کند. تجربه دولوپری (Developers’ experience) یکی از مهمترین معیار ها برای اندازه گیری کیفیت طراحی API شماست.

اصول طراحی RESTful API / بهترین راهکار ها

1. ترمینولوژی

اینها از مهمترین اصطلاح (term) های حوزه REST Api هستند:

  • ـ Resource یک شی یا نمایش از چیزیست (مدل) که به دیتا های دیگر مرتبط است و شامل متد هایی است که روی آن کار هایی انجام میدهند. مثلا حیوانات، مدارس و کارمندان resource هستند و حذف، افزودن و ویرایش کردن افعالی که میتواند روی آنها انجام شود.
  • ـ Collection ها مجموعه ای از resource ها هستند: کمپانی مجموعی از منابع کمپانی است (مثل کارمندان، مشاوران و ... )
  • ـ URL یا Uniform Resource Locator مسیری هستند که میتوانند مکان Resource ها را تعیین کنند و بعضی افعال را روی آنها پیاده کنند.

2. ـ API endpoint

بگذارید برای درک بهتر موضوع چند API برای یک کمپانی با کارمندانش بنویسیم:
برای دریافت لیست همه کارمندان getAllEmployee/ و برای بعضی از کار های معمول دیگر هم لیست زیر را‌ پیاده سازی کرده‌ایم:

  • /addNewEmployee
  • /updateEmployee
  • /deleteEmployee
  • /deleteAllEmployees
  • /promoteEmployee
  • /promoteAllEmployees

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

مشکل کجاست؟
url طبق تعریف (Uniform Resource Locator / مشخص کننده مکان منبع) باید فقط مشخص کننده مکان یک Resource باشد نه انجام فعلی روی آن. پس وجود و getAll . . . در URL اشتباه است.

اصول طراحی RESTful API / بهترین راهکار ها

پس روش درست چیست؟
آدرس companies/ مثال مناسبی از روش صحیح است که هیچ فعلی را مستقیم ذکر نکرده است.اما چگونه باید افعال را به سرور بفهمانیم؟ مثلا اینکه می‌خواهیم لیست کارمندان را دریافت کنیم؟ این کار به عهده‌ HTTP متد هاست (GET, POST, DELETE, PUT) که به آنها verb هم می‌گوییم.

اسم Resource ها همواره باید بصورت جمع بکار برده شوند؛ و اگر خواستیم به یکی از آنها دسترسی داشته باشیم میتوانیم id مورد نظرمان را در URL ارسال کنیم.

  • متد GET برای آدرس companies/ باید لیست همه کمپانی ها را بگیرد.
  • متد GET برای آدرس 34/companies/ باید اطلاعات کمپانی با آی دی 34 را بگیرد.
  • متد DELETE برای آدرس 34/companies/ باید کمپانی با آی دی 34 را حذف کند.

مثال های زیر با فرض این که کارمندان زیر مجموعه ای از کمپانی ها هستند:

  • ـ GET /companies/3/employees برای دریافت لیست همه کارکنان کمپانی 3
  • ـ GET /companies/3/employees/45 برای دریافت اطلاعات کارمند 45 متعلق به شرکت 3
  • ـ DELETE /companies/3/employees/45 برای حذف کارمند 45 متعلق به شرکت 3
  • ـ POST /companiesبرای ساخت یک کمپانی جدید و دریافت اطلاعات کمپانی ساخته شده


حالا API ما تمیز و درست حسابی شد!

نتیجه این که: آدرس ها باید شامل اسم های جمع Resource ها باشند، و HTTP متد ها فعل انجام شده روی Resource را مشخص کنند.

مطالب مشابه