Question

آیا الگو یا best practice معتبری برای امضای URL در سرویس های REST وجود دارد؟ برای مثال یک سرویس REST که می خواهد یک موجودیت خاص را ذخیره کند بهتر است چه URL داشته باشد و یا متد HTTP آن بهتر است GET, POST و یا ... باشد.

Answer 1

url های یک سرویس REST خوب باید ساده باشند و از الگوهایی پیروی کنند تا نیاز به  مستندات را تا حد امکان کاهش دهد.

در url ها از اسم استفاده کنید. از نظر مفهومی بهتر است اسم به صورت جمع بیاید و نه مفرد:

/users
/books/12345

در url ها از فعل استفاده نکنید. استفاده از فعل پادالگو است:

/getAllUsers
/getAdminUsers
/updateBook/12345

استفاده از متدهای HTTP مناسب برای هر عملیات:

• POST: ایجاد
• GET: خواندن
• PUT: ویرایش
• DELETE: حذف

مثال:

منبع	POST	GET	PUT	DELETE
/books	ایجاد یک کتاب	فهرست کتاب‌ها	ویرایش تمام کتاب‌ها	حذف تمام کتاب‌ها
/books/2	خطا	کتاب (با شناسه 2)	ویرایش کتاب در صورت وجود و در غیراینصورت خطا	حذف کتاب

همچنین برای عملیات جستجو بهتر است از query string استفاده شود:

/books?author=ghanbar&category=sport

Comments

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

---

اگر به هر نوع منبع (مثل کتاب)، به عنوان مجموعه‌ای از نمونه‌های آن نگاه نکنیم، شاید استفاده از جمع منطقی به نظر بیاد. :)

---

برای مثال کتاب ها به نظر شما نامگذاری زیر هم درست می باشد ؟
books/categories/{categoryId}

Answer 2

در برخی از موارد از آنجایی که برای ایجاد هیچگاه id ارسال نمی شود و همچنین تقریبا در هیچ برنامه ای امکان ویرایش کردن تمامی داده ها به صورت همزمان در اختیار کاربر قرار داده نمی شود. امضای زیر پیشنهاد داده می شود:

نمونه امضای متد های ReST

URL / متد HTTP	GET	POST	DELETE
/books	دریافت تمام کتابها	ایجاد کتاب جدید	حذف تمام کتابها (معمولا پیاده سازی نمیشود)
/books/:id	دریافت کتاب با شناسه مشخص شده	ویرایش کتاب با شناسه مشخص شده	حذف کتاب با شناسه مشخص شده

 

Answer 3

Best Practices for Designing a Pragmatic RESTful API یکی از بهترین ها در این زمینه است. خیلی جزئیات خوبیو گفته.

Answer 4

1. JSON API - JSON API covers creating and updating resources as well, not just responses.
2. JSend - Simple and probably what you are already doing.
3. OData JSON Protocol - Very complicated.
4. HAL - Like OData but aiming to be HATEOAS like.
5. Google JSON guide