Web API geliştiren herkesin bildiği gibi, bir istekte gönderilen verinin nereden geldiğini, hangi parametreye nasıl bağlandığını bilmek kritik öneme sahiptir. ASP.NET Core, bu süreci yönetmek için güçlü bir model binding mekanizması ve bunu yönlendiren bir dizi öznitelik (attribute) sunar.

Bu yazıda, Web API dünyasında sık kullanılan şu öznitelikleri hem örneklerle hem de kullanım senaryolarıyla ele alıyoruz:

• [FromBody]
• [FromQuery]
• [FromHeader]
• [FromRoute]
• [FromServices]

Ayrıca yazının sonunda öznitelikleri karşılaştıran bir tablo da bulacaksınız.

⭐ Model Binding Öznitelikleri Nedir?

Model binding, HTTP isteği içinden gelen (body, route, query string, header vb.) verileri otomatik olarak:

• Action parametrelerine
• Model sınıflarına
• Nesnelere

deserialize ederek bağlayan mekanizmadır.

Öznitelik kullanmak; uygulamanın neyi nereden aldığı konusunda açıklık, tutarlılık ve hata azaltma sağlar.

🔵 1. [FromBody] – Gövdeden Veri Bağlama

Bir HTTP isteğinin body bölümünde gönderilen JSON verisini modele bağlar.

✔ Ne zaman kullanılır?

• POST, PUT gibi gövde içeren isteklerde
• JSON veya XML veri gönderiliyorsa

✔ Örnek:

[HttpPost]
public IActionResult CreateOrder([FromBody] OrderCreateDTO dto)
{
    // dto artık JSON gövdesinden deserialize edildi.
    return Ok(dto);
}

✔ Gönderilen örnek JSON:

{
  "productId": 5,
  "quantity": 2
}

🔵 2. [FromQuery] – Query String’den Veri Alma

?startDate=...&endDate=... gibi URL’e eklenen parametreleri okur.

✔ Ne zaman kullanılır?

• Filtreleme
• Sayfalama (page, size)
• Arama parametreleri

✔ Örnek:

[HttpGet]
public IActionResult GetOrders([FromQuery] DateTime startDate,
                               [FromQuery] DateTime endDate)
{
    return Ok();
}

✔ Örnek istek:

GET /api/orders?startDate=2024-01-01&endDate=2024-01-31

🔵 3. [FromHeader] – Header’dan Veri Çekme

Özel header bilgilerini okumak için kullanılır.

✔ Ne zaman kullanılır?

• Authentication token
• API Key
• Client metadata

✔ Örnek:

[HttpGet]
public IActionResult GetUser([FromHeader(Name = "Authorization")] string authToken)
{
    return Ok(authToken);
}

🔵 4. [FromRoute] – Route Parametrelerini Alma

URL içindeki dinamik değerleri metod parametresine bağlamak için kullanılır.

✔ Örnek Route:

GET /api/orders/15

✔ Kod:

[HttpGet("{orderId}")]
public IActionResult GetOrder([FromRoute] int orderId)
{
    return Ok(orderId);
}

🔵 5. [FromServices] – Servis Bağımlılığı Enjeksiyonu

Action metoduna doğrudan servis enjekte etmek istediğinizde kullanılır.

✔ Ne zaman kullanılır?

• Sadece o metoda özel operasyon
• Controller seviyesinde DI yapmak istemiyorsanız

✔ Örnek:

[HttpPost]
public IActionResult ProcessOrder([FromServices] IOrderService orderService,
                                  [FromBody] OrderCreateDTO dto)
{
    orderService.Process(dto);
    return Ok();
}

📌 Karşılaştırma Tablosu

📌 Kod Örnekleriyle Tam Bir Controller

Aşağıda tüm özniteliklerin bir arada kullanıldığı örnek bir controller görebilirsin:

[ApiController]
[Route("api/[controller]")]
public class OrdersController : ControllerBase
{
    [HttpPost]
    public IActionResult Create(
        [FromBody] OrderCreateDTO dto,
        [FromHeader(Name = "X-ClientId")] string clientId,
        [FromServices] IOrderService orderService)
    {
        orderService.Process(dto, clientId);
        return Ok("Order created");
    }

    [HttpGet("{orderId}")]
    public IActionResult GetOrder(
        [FromRoute] int orderId,
        [FromQuery] bool includeDetails = false)
    {
        var response = new { Id = orderId, IncludeDetails = includeDetails };
        return Ok(response);
    }
}

Bu yapı bir Web API projesinde tüm temel model binding özniteliklerini gösterir.

🎯 Sonuç

Model binding öznitelikleri, Web API geliştirme sürecinde:

• Veri kaynağının netleşmesini,
• Kod okunabilirliğin artmasını,
• Beklenmeyen hataların azalmasını,

sağlayan önemli yapı taşlarıdır.

Doğru senaryoda doğru öznitelik kullanmak, API’nizin hem stabil hem de sürdürülebilir olmasını sağlar.