Perutean di ASP.NET Web API

Artikel ini menjelaskan cara ASP.NET Web API merutekan permintaan HTTP ke pengontrol.

Catatan

Jika Anda terbiasa dengan ASP.NET MVC, perutean API Web sangat mirip dengan perutean MVC. Perbedaan utamanya adalah api Web menggunakan kata kerja HTTP, bukan jalur URI, untuk memilih tindakan. Anda juga dapat menggunakan perutean gaya MVC di Web API. Artikel ini tidak mengasumsikan pengetahuan apa pun tentang MVC ASP.NET.

Tabel Perutean

Di ASP.NET Web API, pengontrol adalah kelas yang menangani permintaan HTTP. Metode publik pengontrol disebut metode tindakan atau hanya tindakan. Saat kerangka kerja Web API menerima permintaan, kerangka kerja API Web merutekan permintaan ke tindakan.

Untuk menentukan tindakan mana yang akan dipanggil, kerangka kerja menggunakan tabel perutean. Templat proyek Visual Studio untuk Api Web membuat rute default:

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

Rute ini didefinisikan dalam file WebApiConfig.cs , yang ditempatkan di direktori App_Start :

Untuk informasi selengkapnya tentang WebApiConfig kelas , lihat Mengonfigurasi ASP.NET Web API.

Jika Anda menghost sendiri WEB API, Anda harus mengatur tabel perutean langsung pada HttpSelfHostConfiguration objek . Untuk informasi selengkapnya, lihat Menghost sendiri API Web.

Setiap entri dalam tabel perutean berisi templat rute. Templat rute default untuk API Web adalah "api/{controller}/{id}". Dalam templat ini, "api" adalah segmen jalur harfiah, dan {controller} dan {id} adalah variabel tempat penampung.

Ketika kerangka kerja Web API menerima permintaan HTTP, kerangka kerja API Web mencoba mencocokkan URI dengan salah satu templat rute dalam tabel perutean. Jika tidak ada rute yang cocok, klien menerima kesalahan 404. Misalnya, URI berikut cocok dengan rute default:

• /api/contacts
• /api/contacts/1
• /api/products/gizmo1

Namun, URI berikut tidak cocok, karena tidak memiliki segmen "api":

• /contacts/1

Catatan

Alasan untuk menggunakan "api" dalam rute adalah untuk menghindari tabrakan dengan perutean MVC ASP.NET. Dengan demikian, Anda dapat memiliki "/kontak" masuk ke pengontrol MVC, dan "/api/kontak" masuk ke pengontrol API Web. Tentu saja, jika Anda tidak menyukai konvensi ini, Anda dapat mengubah tabel rute default.

Setelah rute yang cocok ditemukan, Web API memilih pengontrol dan tindakan:

• Untuk menemukan pengontrol, Web API menambahkan "Pengontrol" ke nilai variabel {controller }.
• Untuk menemukan tindakan, Web API melihat kata kerja HTTP, lalu mencari tindakan yang namanya dimulai dengan nama kata kerja HTTP tersebut. Misalnya, dengan permintaan GET, Web API mencari tindakan yang diawali dengan "Get", seperti "GetContact" atau "GetAllContacts". Konvensi ini hanya berlaku untuk kata kerja GET, POST, PUT, DELETE, HEAD, OPTIONS, dan PATCH. Anda dapat mengaktifkan kata kerja HTTP lainnya dengan menggunakan atribut pada pengontrol Anda. Kita akan melihat contohnya nanti.
• Variabel tempat penampung lain dalam templat rute, seperti {id}, dipetakan ke parameter tindakan.

Mari kita lihat contohnya. Misalkan Anda menentukan pengontrol berikut:

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

Berikut adalah beberapa kemungkinan permintaan HTTP, bersama dengan tindakan yang dipanggil untuk masing-masing:

Kata Kerja HTTP	Jalur URI	Tindakan	Parameter
GET	api/products	GetAllProducts	(tidak ada)
GET	api/products/4	GetProductById	4
DELETE	api/products/4	DeleteProduct	4
POST	api/products	(tidak ada kecocokan)

Perhatikan bahwa segmen {id} dari URI, jika ada, dipetakan ke parameter id tindakan. Dalam contoh ini, pengontrol mendefinisikan dua metode GET, satu dengan parameter id dan satu tanpa parameter.

Perhatikan juga bahwa permintaan POST akan gagal, karena pengontrol tidak menentukan metode "Posting...".

Variasi Perutean

Bagian sebelumnya menjelaskan mekanisme perutean dasar untuk ASP.NET Web API. Bagian ini menjelaskan beberapa variasi.

Kata kerja HTTP

Alih-alih menggunakan konvensi penamaan untuk kata kerja HTTP, Anda dapat secara eksplisit menentukan kata kerja HTTP untuk tindakan dengan mendekorasi metode tindakan dengan salah satu atribut berikut:

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

Dalam contoh berikut, metode dipetakan FindProduct ke permintaan GET:

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

Untuk mengizinkan beberapa kata kerja HTTP untuk tindakan, atau untuk mengizinkan kata kerja HTTP selain GET, PUT, POST, DELETE, HEAD, OPTIONS, dan PATCH, gunakan [AcceptVerbs] atribut , yang mengambil daftar kata kerja HTTP.

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

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

Perutean menurut Nama Tindakan

Dengan templat perutean default, Web API menggunakan kata kerja HTTP untuk memilih tindakan. Namun, Anda juga dapat membuat rute tempat nama tindakan disertakan dalam URI:

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

Dalam templat rute ini, parameter {action} menamai metode tindakan pada pengontrol. Dengan gaya perutean ini, gunakan atribut untuk menentukan kata kerja HTTP yang diizinkan. Misalnya, pengontrol Anda memiliki metode berikut:

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

Dalam hal ini, permintaan GET untuk "api/products/details/1" akan dipetakan ke Details metode . Gaya perutean ini mirip dengan ASP.NET MVC, dan mungkin sesuai untuk API bergaya RPC.

Anda dapat mengganti nama tindakan dengan menggunakan [ActionName] atribut . Dalam contoh berikut, ada dua tindakan yang memetakan ke "api/products/thumbnail/id. Satu mendukung GET dan yang lain mendukung POST:

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

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

Non-Tindakan

Untuk mencegah metode dipanggil sebagai tindakan, gunakan [NonAction] atribut . Ini memberi sinyal ke kerangka kerja bahwa metode ini bukan tindakan, bahkan jika itu akan cocok dengan aturan perutean.

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

Bacaan lebih lanjut

Topik ini memberikan tampilan perutean tingkat tinggi. Untuk detail selengkapnya, lihat Perutean dan Pemilihan Tindakan, yang menjelaskan dengan tepat bagaimana kerangka kerja mencocokkan URI dengan rute, memilih pengontrol, lalu memilih tindakan yang akan dipanggil.