آشنایی با Web API، معماری Client/Server، HTTP و JSON

.NET 10 | مبانی Web API و قرارداد HTTP

Web API یک قرارداد نرم‌افزاری مبتنی بر HTTP است که Client را از جزئیات پیاده‌سازی Server جدا می‌کند. مسیر استاندارد درخواست از Client آغاز می‌شود، در Endpoint پردازش می‌شود و در قالب Response دارای Status Code، Header و در صورت نیاز Body بازمی‌گردد.

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

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

Web API یک قرارداد نرم‌افزاری مبتنی بر HTTP است که Client را از جزئیات پیاده‌سازی Server جدا می‌کند. مسیر استاندارد درخواست از Client آغاز می‌شود، در Endpoint پردازش می‌شود و در قالب Response دارای Status Code، Header و در صورت نیاز Body بازمی‌گردد.

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

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

در پروژه‌های Controller-based، Controller مرز HTTP است. ورودی از Route، Query، Header یا Body دریافت می‌شود و خروجی به یک پاسخ استاندارد تبدیل می‌شود. جزئیات Data Access نباید در این مرز پنهان شوند.

using Microsoft.AspNetCore.Mvc;

namespace Catalog.Api.Controllers;

[ApiController]
[Route("api/products")]
public sealed class ProductsController : ControllerBase
{
    [HttpGet]
    public IActionResult GetAll()
    {
        return Ok(new[]
        {
            new { Id = 1, Name = "Laptop", Stock = 12 },
            new { Id = 2, Name = "Mouse", Stock = 30 }
        });
    }
}

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

برای دریافت فهرست محصولات، Client یک درخواست GET به مسیر /api/products ارسال می‌کند. Server داده را پردازش کرده و در صورت موفقیت پاسخ 200 OK همراه با آرایه JSON تولید می‌کند.

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

GET /api/products HTTP/1.1
Host: localhost:5000
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json

[
  { "id": 1, "name": "Laptop", "stock": 12 },
  { "id": 2, "name": "Mouse", "stock": 30 }
]

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

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

• URL بر اساس Resource نام‌گذاری شود، نه فعل عملیات.
• برای ایجاد Resource از POST و برای خواندن از GET استفاده شود.
• Status Code بخشی از قرارداد API است و نباید همیشه 200 برگردانده شود.
• Frontend مستقیماً به SQL Server متصل نشود.

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

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

• استفاده از 200 OK برای همه خطاها و موفقیت‌ها.
• ارسال جزئیات Exception داخلی به Client.
• وابستگی مستقیم مدل HTTP به ساختار جدول‌های دیتابیس.
• ترکیب منطق کسب‌وکار با جزئیات Controller.

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

• چرخه Request/Response به‌صورت روشن قابل توضیح است.
• تفاوت 400، 401، 403، 404 و 500 در قرارداد API رعایت می‌شود.
• JSON معتبر و سازگار تولید می‌شود.
• Endpoint اولیه در محیط محلی قابل اجرا و تست است.

7. جمع‌بندی

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