HTTP و طراحی API RESTful

.NET 10 | Resource Design، Idempotency و Status Codes

طراحی RESTful بر مدل‌سازی Resourceها، استفاده معنادار از Methodهای HTTP و پاسخ‌های قابل پیش‌بینی تکیه دارد. کیفیت قرارداد API از هماهنگی Path، Method، Status Code، Header و Body به‌دست می‌آید.

این فصل با تمرکز بر قراردادهای قابل اتکا، مرزبندی مسئولیت‌ها و رفتار قابل پیش‌بینی در محیط واقعی تنظیم شده است. مثال‌ها بر پایه ASP.NET Core و .NET 10 نوشته شده‌اند.

1. چارچوب موضوع و مفاهیم اصلی

طراحی RESTful بر مدل‌سازی Resourceها، استفاده معنادار از Methodهای HTTP و پاسخ‌های قابل پیش‌بینی تکیه دارد. کیفیت قرارداد API از هماهنگی Path، Method، Status Code، Header و Body به‌دست می‌آید.

واژگان و قراردادهای این بخش باید در سراسر پروژه یکدست بمانند؛ تفاوت میان لایه HTTP، منطق برنامه و زیرساخت زمانی روشن می‌ماند که مسئولیت هر جزء به‌صورت صریح تعریف شود.

2. ساختار پیشنهادی در پروژه

مسیرها بهتر است سلسله‌مراتب Domain را بازتاب دهند. Query String برای Filter، Sort و Pagination مناسب است و Actionهای خاص تنها زمانی در مسیر ظاهر می‌شوند که مدل Resource به‌تنهایی بیان کافی نداشته باشد.

GET    /api/products
GET    /api/products/42
POST   /api/products
PUT    /api/products/42
PATCH  /api/products/42
DELETE /api/products/42

GET /api/products?search=laptop&page=2&pageSize=20

3. سناریوی اجرایی

در ایجاد Product جدید، Server پس از موفقیت باید 201 Created تولید کند و در صورت امکان Location همان Resource جدید را در پاسخ قرار دهد. این رفتار Client را از حدس درباره شناسه و آدرس نهایی بی‌نیاز می‌کند.

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

[HttpPost]
public ActionResult<ProductResponse> Create(CreateProductRequest request)
{
    var product = _service.Create(request);
    return CreatedAtAction(
        nameof(GetById),
        new { id = product.Id },
        product);
}

4. اصول طراحی و نگهداری

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

• GET و HEAD نباید Side Effect کسب‌وکاری ایجاد کنند.
• PUT باید در صورت تکرار همان Request نتیجه منطقی پایدار داشته باشد.
• Versioning قرارداد API باید آگاهانه طراحی شود.
• Error Responseها بهتر است ساختار استاندارد مانند ProblemDetails داشته باشند.

5. خطاهای رایج و کنترل آن‌ها

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

• قرار دادن فعل‌هایی مانند getProducts در همه Routeها.
• استفاده از POST برای تمام عملیات صرفاً به دلیل سادگی.
• برگرداندن 201 بدون Location در سناریوی ایجاد Resource.
• طراحی Pathهای عمیق و وابسته به جزئیات دیتابیس.

6. چک‌لیست نهایی فصل

• نام‌گذاری Resourceها یکدست است.
• Method مناسب برای هر عملیات انتخاب شده است.
• Success و Failure Codeها از قبل تعریف شده‌اند.
• Filter و Pagination از Query String استفاده می‌کنند.

7. جمع‌بندی

مفاهیم این فصل زمانی کامل محسوب می‌شوند که هم مسیر موفق و هم مسیر خطا قابل پیش‌بینی، قابل تست و قابل مشاهده باشند. طراحی نهایی باید با Contract API، امنیت و نیازهای نگهداری پروژه هماهنگ بماند.