ASP.NET Web API'sinde yönlendirme

Bu makalede, ASP.NET Web API'lerinin HTTP isteklerini denetleyicilere nasıl yönlendirdiği açıklanır.

Not

ASP.NET MVC hakkında bilginiz varsa, Web API yönlendirmesi MVC yönlendirmesine çok benzer. Temel fark, Web API'sinin eylemi seçmek için URI yolunu değil HTTP fiilini kullanmasıdır. Web API'sinde MVC stili yönlendirmeyi de kullanabilirsiniz. Bu makalede ASP.NET MVC hakkında herhangi bir bilgi varsayılmaz.

Yönlendirme Tabloları

ASP.NET Web API'sinde denetleyici , HTTP isteklerini işleyen bir sınıftır. Denetleyicinin genel yöntemlerine eylem yöntemleri veya basitçe eylemler denir. Web API çerçevesi bir istek aldığında, isteği bir eyleme yönlendirir.

Hangi eylemin çağrıldığını belirlemek için çerçeve bir yönlendirme tablosu kullanır. Web API'sinin Visual Studio proje şablonu varsayılan bir yol oluşturur:

routes.MapHttpRoute(
    name: "API Default",
    routeTemplate: "api/{controller}/{id}",
    defaults: new { id = RouteParameter.Optional }
);

Bu yol, App_Start dizinine yerleştirilen WebApiConfig.cs dosyasında tanımlanır:

Sınıfı hakkında WebApiConfig daha fazla bilgi için bkz . ASP.NET Web API'sini yapılandırma.

Web API'sini kendi kendine barındırdıysanız, yönlendirme tablosunu doğrudan nesne üzerinde HttpSelfHostConfiguration ayarlamanız gerekir. Daha fazla bilgi için bkz. Web API'sini Kendi Kendine Barındırma.

Yönlendirme tablosundaki her giriş bir yol şablonu içerir. Web API'si için varsayılan yol şablonu "api/{controller}/{id}" şeklindedir. Bu şablonda "api" değişmez yol kesimidir ve {controller} ve {id} yer tutucu değişkenleridir.

Web API çerçevesi bir HTTP isteği aldığında, URI'yi yönlendirme tablosundaki yol şablonlarından biriyle eşleştirmeye çalışır. Hiçbir yol eşleşmezse, istemci 404 hatası alır. Örneğin, aşağıdaki URI'ler varsayılan yol ile eşleşti:

• /api/kişiler
• /api/contacts/1
• /api/products/gizmo1

Ancak, "api" kesimi eksik olduğundan aşağıdaki URI eşleşmiyor:

• /contacts/1

Not

Yolda "api" kullanmanın nedeni, ASP.NET MVC yönlendirmesiyle çakışmaları önlemektir. Bu şekilde, "/kişiler" bir MVC denetleyicisine, "/api/contacts" ise bir Web API denetleyicisine gidebilir. Elbette, bu kuralı beğenmezseniz varsayılan yol tablosunu değiştirebilirsiniz.

Eşleşen bir yol bulunduktan sonra Web API'si denetleyiciyi ve eylemi seçer:

• Denetleyiciyi bulmak için Web API'si {controller} değişkeninin değerine "Denetleyici" ekler.
• Eylemi bulmak için Web API'si HTTP fiiline bakar ve ardından adı bu HTTP fiili adıyla başlayan bir eylemi arar. Örneğin, bir GET isteğiyle Web API'sinde "GetContact" veya "GetAllContacts" gibi "Get" ön ekli bir eylem aranıyor. Bu kural yalnızca GET, POST, PUT, DELETE, HEAD, OPTIONS ve PATCH fiilleri için geçerlidir. Denetleyicinizdeki öznitelikleri kullanarak diğer HTTP fiillerini etkinleştirebilirsiniz. Bunun bir örneğini daha sonra göreceğiz.
• Yol şablonundaki {id} gibi diğer yer tutucu değişkenler eylem parametreleriyle eşlenir.

Bir örneğe göz atalım. Aşağıdaki denetleyiciyi tanımladığını varsayalım:

public class ProductsController : ApiController
{
    public IEnumerable<Product> GetAllProducts() { }
    public Product GetProductById(int id) { }
    public HttpResponseMessage DeleteProduct(int id){ }
}

Olası HTTP isteklerinin yanı sıra her birine çağrılan eylem şunlardır:

HTTP Fiili	URI Yolu	Eylem	Parametre
GET	api/products	GetAllProducts	(yok)
GET	api/products/4	GetProductById	4
DELETE	api/products/4	DeleteProduct	4
POST	api/products	(eşleşme yok)

Varsa URI'nin {id} kesiminin eylemin id parametresiyle eşlendiğine dikkat edin. Bu örnekte denetleyici, biri kimlik parametresi ve diğeri parametresiz olan iki GET yöntemini tanımlar.

Ayrıca, denetleyici bir "Post..." yöntemi tanımlamadığından POST isteğinin başarısız olacağını unutmayın.

Yönlendirme Varyasyonları

Önceki bölümde ASP.NET Web API'sine yönelik temel yönlendirme mekanizması açıklanmıştır. Bu bölümde bazı varyasyonlar açıklanmaktadır.

HTTP fiilleri

HTTP fiilleri için adlandırma kuralını kullanmak yerine, eylem yöntemini aşağıdaki özniteliklerden biriyle süsleyerek bir eylem için HTTP fiilini açıkça belirtebilirsiniz:

• [HttpGet]
• [HttpPut]
• [HttpPost]
• [HttpDelete]
• [HttpHead]
• [HttpOptions]
• [HttpPatch]

Aşağıdaki örnekte yöntemi GET FindProduct istekleriyle eşlenir:

public class ProductsController : ApiController
{
    [HttpGet]
    public Product FindProduct(id) {}
}

Bir eylem için birden çok HTTP fiiline izin vermek veya GET, PUT, POST, DELETE, HEAD, OPTIONS ve PATCH dışındaki HTTP fiillerine izin vermek için, HTTP fiillerinin listesini alan özniteliğini kullanın [AcceptVerbs] .

public class ProductsController : ApiController
{
    [AcceptVerbs("GET", "HEAD")]
    public Product FindProduct(id) { }

    // WebDAV method
    [AcceptVerbs("MKCOL")]
    public void MakeCollection() { }
}

Eylem Adına Göre Yönlendirme

Varsayılan yönlendirme şablonuyla, Web API eylemini seçmek için HTTP fiilini kullanır. Ancak, eylem adının URI'ye eklendiği bir yol da oluşturabilirsiniz:

routes.MapHttpRoute(
    name: "ActionApi",
    routeTemplate: "api/{controller}/{action}/{id}",
    defaults: new { id = RouteParameter.Optional }
);

Bu yol şablonunda , {action} parametresi denetleyicideki eylem yöntemini adlandırın. Bu yönlendirme stiliyle, izin verilen HTTP fiillerini belirtmek için öznitelikleri kullanın. Örneğin, denetleyicinizin aşağıdaki yönteme sahip olduğunu varsayalım:

public class ProductsController : ApiController
{
    [HttpGet]
    public string Details(int id);
}

Bu durumda, "api/products/details/1" için bir GET isteği yöntemine Details eş olacaktır. Bu yönlendirme stili ASP.NET MVC'ye benzer ve RPC stili api için uygun olabilir.

özniteliğini kullanarak [ActionName] eylem adını geçersiz kılabilirsiniz. Aşağıdaki örnekte,"api/products/thumbnail/id" ile eşleyen iki eylem vardır. Biri GET'yi, diğeri POST'yi destekler:

public class ProductsController : ApiController
{
    [HttpGet]
    [ActionName("Thumbnail")]
    public HttpResponseMessage GetThumbnailImage(int id);

    [HttpPost]
    [ActionName("Thumbnail")]
    public void AddThumbnailImage(int id);
}

Eylem Dışı

Bir yöntemin eylem olarak çağrılmasını önlemek için özniteliğini [NonAction] kullanın. Bu, aksi takdirde yönlendirme kurallarıyla eşleşse bile yöntemin bir eylem olmadığını çerçeveye bildirir.

// Not an action method.
[NonAction]  
public string GetPrivateData() { ... }

Daha Fazla Bilgi

Bu konu başlığında yönlendirmenin üst düzey bir görünümü sağlanmıştır. Daha fazla ayrıntı için bkz. Çerçevenin bir URI ile bir yol arasında tam olarak nasıl eşleşdiğini açıklayan Yönlendirme ve Eylem Seçimi, bir denetleyici seçer ve ardından çağrılacak eylemi seçer.