Mengaktifkan Operasi CRUD di ASP.NET Web API 1

oleh Mike Wasson

Unduh Proyek yang Selesai

Tutorial ini menunjukkan cara mendukung operasi CRUD dalam layanan HTTP menggunakan ASP.NET Web API untuk ASP.NET 4.x.

Versi perangkat lunak yang digunakan dalam tutorial

• Visual Studio 2012
• Web API 1 (juga berfungsi dengan Web API 2)

CRUD adalah singkatan dari "Buat, Baca, Perbarui, dan Hapus," yang merupakan empat operasi database dasar. Banyak layanan HTTP juga memodelkan operasi CRUD melalui REST atau API seperti REST.

Dalam tutorial ini, Anda akan membangun API web yang sangat sederhana untuk mengelola daftar produk. Setiap produk akan berisi nama, harga, dan kategori (seperti "mainan" atau "perangkat keras"), ditambah ID produk.

API produk akan mengekspos metode berikut.

Tindakan	Metode HTTP	URI relatif
Mendapatkan daftar semua produk	GET	/api/products
Mendapatkan produk berdasarkan ID	GET	/api/products/id
Mendapatkan produk menurut kategori	GET	/api/products?category=category
Membuat produk baru	POST	/api/products
Memperbarui produk	PUT	/api/products/id
Menghapus produk	DELETE	/api/products/id

Perhatikan bahwa beberapa URI menyertakan ID produk di jalur. Misalnya, untuk mendapatkan produk yang ID-nya adalah 28, klien mengirimkan permintaan GET untuk http://hostname/api/products/28.

Sumber

API produk mendefinisikan URI untuk dua jenis sumber daya:

Sumber daya	URI
Daftar semua produk.	/api/products
Produk individu.	/api/products/id

Metode

Empat metode HTTP utama (GET, PUT, POST, dan DELETE) dapat dipetakan ke operasi CRUD sebagai berikut:

• GET mengambil representasi sumber daya pada URI tertentu. GET seharusnya tidak memiliki efek samping pada server.
• PUT memperbarui sumber daya pada URI tertentu. PUT juga dapat digunakan untuk membuat sumber daya baru di URI tertentu, jika server memungkinkan klien untuk menentukan URI baru. Untuk tutorial ini, API tidak akan mendukung pembuatan melalui PUT.
• POST membuat sumber daya baru. Server menetapkan URI untuk objek baru dan mengembalikan URI ini sebagai bagian dari pesan respons.
• DELETE menghapus sumber daya pada URI tertentu.

Catatan: Metode PUT menggantikan seluruh entitas produk. Artinya, klien diharapkan untuk mengirim representasi lengkap dari produk yang diperbarui. Jika Anda ingin mendukung pembaruan parsial, metode PATCH lebih disukai. Tutorial ini tidak menerapkan PATCH.

Membuat Proyek API Web Baru

Mulailah dengan menjalankan Visual Studio dan pilih Proyek Baru dari halaman Mulai . Atau, dari menu File , pilih Baru lalu Proyek.

Di panel Templat , pilih Templat terinstal dan perluas simpul Visual C# . Di bawah Visual C#, pilih Web. Dalam daftar templat proyek, pilih ASP.NET Aplikasi Web MVC 4. Beri nama proyek "ProductStore" dan klik OK.

Dalam dialog Proyek ASP.NET Baru MVC 4 , pilih API Web dan klik OK.

Menambahkan Model

Model adalah objek yang mewakili data dalam aplikasi Anda. Dalam ASP.NET Web API, Anda dapat menggunakan objek CLR yang ditik dengan kuat sebagai model, dan objek tersebut akan secara otomatis diserialisasikan ke XML atau JSON untuk klien.

Untuk PRODUCTStore API, data kami terdiri dari produk, jadi kami akan membuat kelas baru bernama Product.

Jika Penjelajah Solusi belum terlihat, klik menu Tampilan dan pilih Penjelajah Solusi. Di Penjelajah Solusi, klik kanan folder Model . Dari menu konteks, pilih Tambahkan, lalu pilih Kelas. Beri nama kelas "Produk".

Tambahkan properti berikut ke Product kelas .

namespace ProductStore.Models
{
    public class Product
    {
        public int Id { get; set; }
        public string Name { get; set; }
        public string Category { get; set; }
        public decimal Price { get; set; }
    }
}

Menambahkan Repositori

Kita perlu menyimpan koleksi produk. Sebaiknya pisahkan koleksi dari implementasi layanan kami. Dengan begitu, kita dapat mengubah backing store tanpa menulis ulang kelas layanan. Jenis desain ini disebut pola repositori . Mulailah dengan mendefinisikan antarmuka generik untuk repositori.

Di Penjelajah Solusi, klik kanan folder Model . Pilih Tambahkan, lalu pilih Item Baru.

Di panel Templat , pilih Templat terinstal dan perluas simpul C#. Di bawah C#, pilih Kode. Dalam daftar templat kode, pilih Antarmuka. Beri nama antarmuka "IProductRepository".

Tambahkan implementasi berikut:

namespace ProductStore.Models
{
    public interface IProductRepository
    {
        IEnumerable<Product> GetAll();
        Product Get(int id);
        Product Add(Product item);
        void Remove(int id);
        bool Update(Product item);
    }
}

Sekarang tambahkan kelas lain ke folder Model, bernama "ProductRepository." Kelas ini akan mengimplementasikan IProductRepository antarmuka. Tambahkan implementasi berikut:

namespace ProductStore.Models
{
    public class ProductRepository : IProductRepository
    {
        private List<Product> products = new List<Product>();
        private int _nextId = 1;

        public ProductRepository()
        {
            Add(new Product { Name = "Tomato soup", Category = "Groceries", Price = 1.39M });
            Add(new Product { Name = "Yo-yo", Category = "Toys", Price = 3.75M });
            Add(new Product { Name = "Hammer", Category = "Hardware", Price = 16.99M });
        }

        public IEnumerable<Product> GetAll()
        {
            return products;
        }

        public Product Get(int id)
        {
            return products.Find(p => p.Id == id);
        }

        public Product Add(Product item)
        {
            if (item == null)
            {
                throw new ArgumentNullException("item");
            }
            item.Id = _nextId++;
            products.Add(item);
            return item;
        }

        public void Remove(int id)
        {
            products.RemoveAll(p => p.Id == id);
        }

        public bool Update(Product item)
        {
            if (item == null)
            {
                throw new ArgumentNullException("item");
            }
            int index = products.FindIndex(p => p.Id == item.Id);
            if (index == -1)
            {
                return false;
            }
            products.RemoveAt(index);
            products.Add(item);
            return true;
        }
    }
}

Repositori menyimpan daftar dalam memori lokal. Ini OK untuk tutorial, tetapi dalam aplikasi nyata, Anda akan menyimpan data secara eksternal, baik database atau di penyimpanan cloud. Pola repositori akan mempermudah perubahan implementasi nanti.

Menambahkan Pengontrol API Web

Jika Anda telah bekerja dengan ASP.NET MVC, maka Anda sudah terbiasa dengan pengontrol. Di ASP.NET Web API, pengontrol adalah kelas yang menangani permintaan HTTP dari klien. Wizard Proyek Baru membuat dua pengontrol untuk Anda saat membuat proyek. Untuk melihatnya, perluas folder Pengontrol di Penjelajah Solusi.

• HomeController adalah pengontrol MVC ASP.NET tradisional. Ini bertanggung jawab untuk melayani halaman HTML untuk situs, dan tidak terkait langsung dengan API web kami.
• ValuesController adalah contoh pengontrol WebAPI.

Lanjutkan dan hapus ValuesController, dengan mengklik kanan file di Penjelajah Solusi dan memilih Hapus. Sekarang tambahkan pengontrol baru, sebagai berikut:

Di Penjelajah Solusi, klik kanan folder Pengontrol. Pilih Tambahkan lalu pilih Pengontrol.

Di wizard Tambahkan Pengontrol , beri nama pengontrol "ProductsController". Di daftar drop-down Templat , pilih Pengontrol API Kosong. Kemudian klik Tambahkan

Catatan

Tidak perlu memasukkan pengontrol Anda ke dalam folder bernama Pengontrol. Nama folder tidak penting; ini hanyalah cara mudah untuk mengatur file sumber Anda.

Wizard Tambahkan Pengontrol akan membuat file bernama ProductsController.cs di folder Pengontrol. Jika file ini belum dibuka, klik dua kali file untuk membukanya. Tambahkan pernyataan penggunaan berikut:

using ProductStore.Models;

Tambahkan bidang yang menyimpan instans IProductRepository .

public class ProductsController : ApiController
{
    static readonly IProductRepository repository = new ProductRepository();
}

Catatan

Panggilan new ProductRepository() di pengontrol bukanlah desain terbaik, karena mengikat pengontrol dengan implementasi tertentu dari IProductRepository. Untuk pendekatan yang lebih baik, lihat Menggunakan Penyelesai Dependensi API Web.

Mendapatkan Sumber Daya

PRODUCTStore API akan mengekspos beberapa tindakan "baca" sebagai metode HTTP GET. Setiap tindakan akan sesuai dengan metode di ProductsController kelas .

Tindakan	Metode HTTP	URI relatif
Mendapatkan daftar semua produk	GET	/api/products
Mendapatkan produk berdasarkan ID	GET	/api/products/id
Mendapatkan produk menurut kategori	GET	/api/products?category=category

Untuk mendapatkan daftar semua produk, tambahkan metode ini ke ProductsController kelas :

public class ProductsController : ApiController
{
    public IEnumerable<Product> GetAllProducts()
    {
        return repository.GetAll();
    }
    // ....
}

Nama metode dimulai dengan "Get", jadi dengan konvensi itu memetakan ke permintaan GET. Selain itu, karena metode tidak memiliki parameter, metode ini memetakan ke URI yang tidak berisi segmen "id" di jalur.

Untuk mendapatkan produk berdasarkan ID, tambahkan metode ini ke ProductsController kelas :

public Product GetProduct(int id)
{
    Product item = repository.Get(id);
    if (item == null)
    {
        throw new HttpResponseException(HttpStatusCode.NotFound); 
    }
    return item;
}

Nama metode ini juga dimulai dengan "Get", tetapi metode ini memiliki parameter bernama id. Parameter ini dipetakan ke segmen "id" dari jalur URI. Kerangka kerja ASP.NET Web API secara otomatis mengonversi ID ke jenis data (int) yang benar untuk parameter .

Metode GetProduct memberikan pengecualian jenis HttpResponseException jika id tidak valid. Pengecualian ini akan diterjemahkan oleh kerangka kerja ke dalam kesalahan 404 (Tidak Ditemukan).

Terakhir, tambahkan metode untuk menemukan produk menurut kategori:

public IEnumerable<Product> GetProductsByCategory(string category)
{
    return repository.GetAll().Where(
        p => string.Equals(p.Category, category, StringComparison.OrdinalIgnoreCase));
}

Jika URI permintaan memiliki string kueri, Web API mencoba mencocokkan parameter kueri dengan parameter pada metode pengontrol. Oleh karena itu, URI formulir "api/products?category=category" akan dipetakan ke metode ini.

Membuat Sumber Daya

Selanjutnya, kita akan menambahkan metode ke ProductsController kelas untuk membuat produk baru. Berikut adalah implementasi sederhana dari metode ini:

// Not the final implementation!
public Product PostProduct(Product item)
{
    item = repository.Add(item);
    return item;
}

Perhatikan dua hal tentang metode ini:

• Nama metode dimulai dengan "Post...". Untuk membuat produk baru, klien mengirimkan permintaan HTTP POST.
• Metode ini mengambil parameter jenis Produk. Di API Web, parameter dengan jenis kompleks dideserialisasi dari isi permintaan. Oleh karena itu, kami mengharapkan klien untuk mengirim representasi serial objek produk, baik dalam format XML atau JSON.

Implementasi ini akan berfungsi, tetapi belum cukup lengkap. Idealnya, kami ingin respons HTTP menyertakan yang berikut:

• Kode respons: Secara default, kerangka kerja API Web menetapkan kode status respons ke 200 (OK). Tetapi menurut protokol HTTP/1.1, ketika permintaan POST menghasilkan pembuatan sumber daya, server harus membalas dengan status 201 (Dibuat).
• Lokasi: Saat server membuat sumber daya, server harus menyertakan URI sumber daya baru di header Lokasi respons.

ASP.NET Web API memudahkan untuk memanipulasi pesan respons HTTP. Berikut adalah implementasi yang ditingkatkan:

public HttpResponseMessage PostProduct(Product item)
{
    item = repository.Add(item);
    var response = Request.CreateResponse<Product>(HttpStatusCode.Created, item);

    string uri = Url.Link("DefaultApi", new { id = item.Id });
    response.Headers.Location = new Uri(uri);
    return response;
}

Perhatikan bahwa jenis pengembalian metode sekarang adalah HttpResponseMessage. Dengan mengembalikan HttpResponseMessage alih-alih Produk, kita dapat mengontrol detail pesan respons HTTP, termasuk kode status dan header Lokasi.

Metode CreateResponse membuat HttpResponseMessage dan secara otomatis menulis representasi berseri objek Produk ke dalam isi untuk pesan respons.

Catatan

Contoh ini tidak memvalidasi Product. Untuk informasi tentang validasi model, lihat Validasi Model di ASP.NET Web API.

Memperbarui Sumber Daya

Memperbarui produk dengan PUT sangat mudah:

public void PutProduct(int id, Product product)
{
    product.Id = id;
    if (!repository.Update(product))
    {
        throw new HttpResponseException(HttpStatusCode.NotFound);
    }
}

Nama metode dimulai dengan "Put...", sehingga Web API mencocokkannya dengan permintaan PUT. Metode ini mengambil dua parameter, ID produk dan produk yang diperbarui. Parameter id diambil dari jalur URI, dan parameter produk dideserialisasi dari isi permintaan. Secara default, kerangka kerja ASP.NET Web API mengambil jenis parameter sederhana dari rute dan jenis kompleks dari isi permintaan.

Menghapus Sumber Daya

Untuk menghapus sumber daya, tentukan "Hapus..." Metode.

public void DeleteProduct(int id)
{
    Product item = repository.Get(id);
    if (item == null)
    {
        throw new HttpResponseException(HttpStatusCode.NotFound);
    }

    repository.Remove(id);
}

Jika permintaan DELETE berhasil, permintaan dapat mengembalikan status 200 (OK) dengan isi entitas yang menjelaskan status; status 202 (Diterima) jika penghapusan masih tertunda; atau status 204 (Tanpa Konten) tanpa badan entitas. Dalam hal ini, DeleteProduct metode ini memiliki void jenis pengembalian, jadi ASP.NET Web API secara otomatis menerjemahkan ini ke dalam kode status 204 (Tanpa Konten).