API & REST Tutorial فصل ۲ — طراحی REST درس آموزشی

منابع، آدرس‌ها و ساختار REST درست

REST یعنی برنامه را «منابع» (Resource) ببینید که آدرس دارند و با متدهای HTTP کار می‌کنند. آدرس خوب اسم است نه فعل: /orders نه /createOrder؛ جمع‌بندی‌ها روابط را نشان می‌دهند: /orders/42/items. یک قرارداد آدرس‌دهی منظم، نیمی از مستندسازی است.

مراحل قدم‌به‌قدم

  1. ۱

    اسم، جمع و سلسله‌مراتب

    /users، /users/42، /users/42/orders — تمرکز بر اسم جمع و روابط parent/child. افعال (GET برای واکشی) از متد می‌آیند نه URL. برای عمل‌های غیر CRUD (مثل ارسال) الگوی زیرمنبع عمل: POST /orders/42/send.

  2. ۲

    پارامتر مسیر و کوئری

    شناسایی منبع با مسیر (/users/42)؛ فیلتر و صفحه‌بندی و مرتب‌سازی با query: /users?city=tehran&page=2&sort=-created_at&per_page=20. این قرارداد را مستند کنید و همه‌جا یکسان نگه دارید.

  3. ۳

    پاسخ لیست با meta

    پاسخ لیست همیشه: { data: [...], meta: { page, per_page, total, next } }. کلاینت بدون حدس صفحه بعد را می‌سازد. کورسور (cursor) برای لیست‌های خیلی بزرگ جایگزین page می‌شود.

  4. ۴

    قناعت در فیلدها

    همه ستون‌های دیتابیس را نفروشید؛ فیلدهای پاسخ را انتخاب کنید و گزینه fields= برای درخواست سبک‌تر بدهید. پاسخ API مالکیت عمومی است — هر فیلد اضافه، قرارداد تبعی‌پذیر.

نکات مهم

  • ◆ URL اسم است؛ فعل متد HTTP است — هرگز /createOrder نه.
  • ◆ روابط را در مسیر نشان دهید؛ فیلتر و صفحه با query.
  • ◆ پاسخ لیست بدون meta ناقص است؛ صفحه‌بندی قرارداد است.

کد یا مسیر نمونه

# طراحی صحیح نقاط انتهایی فروشگاه:
GET    /v1/products              # فهرست (فیلتر: ?category=2&sort=price)
POST   /v1/products              # ساخت
GET    /v1/products/42           # جزئیات
PATCH  /v1/products/42           # ویرایش جزئی
DELETE /v1/products/42           # حذف
GET    /v1/orders/99/items       # اقلام یک سفارش
POST   /v1/orders/99/pay         # عمل غیر CRUD

# نمونه پاسخ لیست:
# {
#   "data": [ { "id": 42, "name": "هندزفری", "price": 250000 } ],
#   "meta": { "page": 1, "per_page": 20, "total": 137, "next": "/v1/products?page=2" }
# }

پرسش و پاسخ این درس (۰)

هنوز دیدگاهی ثبت نشده؛ اولین نفر باشید!

دیدگاه خود را بنویسید

کپچا

دیدگاه شما پس از تأیید مدیر نمایش داده می‌شود.