Mengembangkan API Web ASP.NET

Indonesian (Bahasa Indonesia) translation by Ilham Saputra (you can also view the original English article)

ASP.NET Web API adalah kerangka kerja untuk membangun API web di atas .NET Framework yang memanfaatkan HTTP. Karena hampir semua platform yang Anda anggap memiliki perpustakaan HTTP, layanan HTTP dapat dikonsumsi oleh berbagai klien, termasuk browser, perangkat seluler, dan aplikasi desktop tradisional.

ASP.NET Web API memanfaatkan konsep-konsep HTTP dan menyediakan fitur-fitur seperti:

Jenis Permintaan/Respons berbeda yang didukung seperti HTML, JSON dan File Biner (gambar/audio/video) dan bukan hanya konten XML seperti yang disyaratkan oleh SOAP.
Built-in Action Mapping in controller, berdasarkan kata kerja HTTP (GET, POST, dll.)

Membuat API Web

Untuk membuat API Web, kami akan menggunakan Visual Studio. Jika Anda memiliki Visual Studio 2012 atau versi yang lebih tinggi, maka Anda semua baik untuk memulai dengan API Web Anda.

Memulai Proyek Baru

Dari menu File, pilih New dan kemudian Project.

Di panel Templates, pilih Installed Templates dan perluas node Visual C#. Di bawah Visual C#, pilih Web. Dalam daftar templat proyek, pilih ASP.NET Web Application. Tetapkan nama yang Anda sukai untuk proyek dan klik OK.

Di jendela berikutnya, Anda akan disajikan daftar template. Meskipun Anda dapat memilih salah satu template dari daftar karena semuanya akan berisi file DLL dan konfigurasi yang diperlukan untuk membuat pengontrol API Web, kami akan memilih Template Empty Project untuk memulai.

Menambahkan Controller

Di Web API, controller adalah objek yang menangani permintaan HTTP. Mari kita cepat menambahkan controller untuk menguji Web API kita.

Di Solution Explorer, klik kanan folder Controllers. Pilih Add dan kemudian pilih Controller. Kami akan memanggil controller TestController dan pilih Empty API Controller dari opsi Scaffolding untuk Templat.

Visual Studio akan membuat controller kami yang berasal dari kelas ApiController. Mari kita tambahkan fungsi cepat di sini untuk menguji proyek API kami dengan hosting di IIS.

public IEnumerable<string> Get()
        {
            return new string[] { "hello", "world" };
        }

Hosting di IIS

Sekarang kami akan menambahkan layanan kami di IIS sehingga kami dapat mengaksesnya secara lokal. Buka IIS dan klik kanan pada Default Web Site untuk menambahkan layanan web kami.

Di kotak dialog Add Application, beri nama TestAPI layanan Anda dan berikan jalur ke jalur root proyek Visual Studio seperti yang ditunjukkan di bawah ini.

Klik OK dan Layanan API Web kami siap.

Untuk menguji apakah semuanya berfungsi dengan baik, mari coba URL berikut di browser apa saja: http://localhost/TestAPI/api/test.

Jika Anda telah menamai pengontrol Anda TestController seperti yang saya miliki dan juga menamai layanan web Anda di IIS sebagai TestAPI maka peramban Anda harus mengembalikan file XML seperti yang ditunjukkan di bawah ini dengan nilai string hello world.

Namun, jika IIS Anda tidak memiliki izin untuk folder proyek, Anda mungkin mendapatkan pesan kesalahan yang mengatakan: "Halaman yang diminta tidak dapat diakses karena data konfigurasi terkait untuk halaman tidak valid."

Jika Anda mendapatkan jenis kesalahan ini maka Anda dapat menyelesaikannya dengan memberikan akses baca / tulis ke grup pengguna IIS_IUSRS ke folder root.

Routing

Sekarang mari kita lihat bagaimana URL yang kami sediakan untuk browser bekerja.

Routing ASP.NET menangani proses menerima permintaan dan memetakannya ke tindakan pengontrol. Perutean Web API mirip dengan perutean MVC tetapi dengan beberapa perbedaan; Web API menggunakan jenis permintaan HTTP alih-alih nama tindakan di URL (seperti dalam kasus MVC) untuk memilih tindakan yang akan dieksekusi di controller.

Konfigurasi perutean untuk Web API didefinisikan dalam file WebApiConfig.cs. Default konfigurasi perutean ASP.NET Web API adalah seperti yang ditunjukkan dalam berikut:

public static class WebApiConfig
    {
        public static void Register(HttpConfiguration config)
        {
            config.Routes.MapHttpRoute(
                name: "DefaultApi",
                routeTemplate: "api/{controller}/{id}",
                defaults: new { id = RouteParameter.Optional }
            );
        }
    }

Templat perutean default API Web adalah api/{controller}/{id}. Itulah sebabnya kami memiliki "api" di URL kami http://localhost/TestAPI/api/test.

Ketika Web API menerima sebuah GET permintaan untuk controller tertentu, daftar tindakan pencocokan semua metode yang namanya dimulai dengan mendapatkan. Sama halnya dengan semua kata HTTP lainnya. Metode aksi benar dipanggil dikenalpasti oleh pencocokan tanda tangan dari metode.

Konvensi penamaan untuk metode tindakan ini dapat diganti dengan menggunakan HttpGet,
HttpPut, HttpPost, atau HttpDelete atribut dengan metode aksi.

Jadi, jika kita mengganti kode sebelumnya dengan ini:

[HttpGet]
        public IEnumerable<string> Hello()
        {
            return new string[] { "hello", "world" };
        }

Dan tekan http://localhost/TestAPI/api/test di browser kami, ini masih akan mengembalikan hasil yang sama. Jika kami menghapus atribut HttpGet, API Web kami tidak akan dapat menemukan Tindakan yang cocok dengan permintaan kami.

Sekarang, mari kita tambahkan metode lain dengan nama yang sama Hello tetapi dengan tanda tangan yang berbeda.

[HttpGet]
        public IEnumerable<string> Hello(string id)
        {
            return new string[] { id, "world" };
        }

Dengan menggunakan metode ini, kami sekarang dapat mengontrol apa yang dikembalikan dari Layanan kami sampai batas tertentu. Jika kami menguji metode ini dengan memanggil http://localhost/TestAPI/api/test/namaste (perhatikan parameter tambahan di akhir URL), kami akan mendapatkan hasil sebagai berikut:

Jadi, sekarang kita memiliki dua metode yang disebut Hello. Seseorang tidak mengambil parameter apa pun dan mengembalikan string "hello world", dan metode lain mengambil satu parameter dan mengembalikan "yourparameter world".

Meskipun kami belum memberikan nama metode yang akan dieksekusi di URL kami, perutean ASP.NET default memahami permintaan sebagai permintaan GET dan berdasarkan pada tanda tangan permintaan (parameter yang disediakan), metode tertentu dijalankan. Ini bagus jika kita hanya memiliki satu metode GET atau POST di controller kita, tetapi karena dalam aplikasi bisnis nyata biasanya akan ada lebih dari satu metode GET tersebut, perutean default ini tidak cukup.

Mari kita menambahkan Metode GET lain untuk melihat bagaimana default routing menangani itu.

[HttpGet]
        public IEnumerable<string> GoodBye()
        {
            return new string[] { "good bye", "world" };
        }

Jika sekarang kami membangun proyek kami dan memanggil http://localhost/TestAPI/api/test/ di browser kami, kami akan mendapatkan kesalahan yang mengatakan "Beberapa tindakan ditemukan yang cocok dengan permintaan", yang berarti sistem perutean mengidentifikasi dua tindakan yang cocok dengan permintaan GET.

Menyesuaikan Sistem Perutean Default API Web

Agar dapat menggunakan beberapa Dapatkan permintaan dari controller sama, kita perlu mengubah HTTP permintaan jenis pengenal dengan pengidentifikasi berbasis tindakan sehingga beberapa mendapatkan permintaan dapat disebut.

Ini dapat dilakukan dengan menambahkan konfigurasi rute berikut sebelum konfigurasi default di WebApiConfig.cs.

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

Sekarang uji semua tiga metode dengan menelepon URL ini:

Struktur Layanan API Web untuk Perangkat Seluler

Sekarang setelah gagasan dasar tentang bagaimana Tindakan dari Pengontrol dapat diekspos melalui API dipahami, mari lihat bagaimana Layanan API dapat dirancang untuk klien.

Pipa permintaan API Web ASP.NET menerima permintaan dari aplikasi klien, dan metode tindakan dalam pengontrol akan dipanggil. Metode tindakan akan, pada gilirannya, memanggil lapisan Bisnis untuk mengambil atau memperbarui data, yang, pada gilirannya, memanggil kelas Repositori untuk mengembalikan data dari database.

Berdasarkan pola desain ini, mari kita buat sampel API yang memperlihatkan daftar item yang diklasifikasikan sebagai layanan kepada kliennya.

Membuat kelas yang disebut ClassifiedModel di dalam folder Models.

public class ClassifiedModel
    {
        public int ClassifiedID { get; set; }
        public string ClassifiedTitle { get; set; }
        public string ClassifiedDetail { get; set; }
        public DateTime CreatedDate { get; set; }
        public string ClassifiedImage { get; set; }
    }

Membuat dua folder BLL dan DAL mewakili lapisan logika bisnis dan Layer akses Data.

Membuat kelas yang disebut ClassifiedRepository di dalam folder DAL mana kita akan keras-kode beberapa data untuk daftar diklasifikasikan dan mengekspos daftar melalui metode statis.

public class ClassifiedRepository
    {
        //list of Classified Objects
        public static List<ClassifiedModel> classifiedList;

        /// <summary>
        /// get list of classified models
        /// </summary>
        /// <returns></returns>
        public static List<ClassifiedModel> GetClassifiedsList()
        {
            if (classifiedList == null
            || classifiedList.Count == 0)
            {
                CreateClassifiedsList();
            }
            return classifiedList;
        }

        /// <summary>
        /// Init a list of classified items
        /// </summary>
        private static void CreateClassifiedsList()
        {
            classifiedList = new List<ClassifiedModel>()
            {
                new ClassifiedModel()
                {
                    ClassifiedID = 1,
                    ClassifiedTitle = "Car on Sale",
                    ClassifiedDetail = "Car details car details car details",
                    CreatedDate = DateTime.Now,
                    ClassifiedImage = "/carImageUrl.jpg"
                },

                new ClassifiedModel()
                {
                    ClassifiedID = 2,
                    ClassifiedTitle = "House on Sale",
                    ClassifiedDetail = "House details house details house details",
                    CreatedDate = DateTime.Now,
                    ClassifiedImage = "/houseImageUrl.jpg"
                },

                new ClassifiedModel()
                {
                    ClassifiedID = 3,
                    ClassifiedTitle = "Room for rent",
                    ClassifiedDetail = "Room details room details room details",
                    CreatedDate = DateTime.Now,
                    ClassifiedImage = "/roomImageUrl.jpg"
                },

                new ClassifiedModel()
                {
                    ClassifiedID = 4,
                    ClassifiedTitle = "Tree on Sale",
                    ClassifiedDetail = "Tree details tree details tree details",
                    CreatedDate = DateTime.Now,
                    ClassifiedImage = "/treeImageUrl.jpg"
                }

            };
        }
    }

Mari kita tambahkan kelas lain ClassifiedService di dalam folder BLL sekarang. Kelas ini akan berisi metode statis untuk mengakses repositori dan kembali obyek bisnis ke controller. Berdasarkan parameter pencarian, metode akan kembali daftar item baris.

public class ClassifiedService
    {
        public static List<ClassifiedModel> GetClassifieds(string searchQuery)
        {
            var classifiedList = ClassifiedRepository.GetClassifiedsList();

            if (!string.IsNullOrEmpty(searchQuery))
            {
                return (from m in classifiedList
                        where m.ClassifiedTitle.StartsWith(searchQuery, StringComparison.CurrentCultureIgnoreCase)
                        select m).ToList();
            }
            return classifiedList;
        }       
    }

Akhirnya, sekarang kita akan menciptakan kami Web API controller untuk diklasifikasikan daftar metode terkait.

Mirip dengan cara kami membuat TestController pertama kami, mari kita buat pengontrol API dengan tindakan baca / tulis kosong yang disebut ClassifiedsController dan tambahkan dua metode Tindakan berikut.

public class ClassifiedsController : ApiController
    {
        public List<ClassifiedModel> Get(string id)
        {
            return ClassifiedService.GetClassifieds(id);
        }
        public List<ClassifiedModel> Get()
        {
            return ClassifiedService.GetClassifieds("");
        }
    }

Sekarang, kami memiliki dua Tindakan yang diekspos melalui API. Metode GET pertama akan dipanggil jika ada kata kunci yang akan dicari yang diteruskan bersama dengan permintaan. Jika tidak ada parameter input, maka metode GET kedua akan dipanggil. Kedua metode akan mengembalikan daftar objek model Rahasia kami.

Jangan lupa untuk menambahkan semua referensi yang diperlukan ke ruang nama di setiap file kelas yang ditambahkan. Bangun proyek, dan kami siap untuk menguji kedua metode ini sekarang.

Untuk menampilkan hasil yang mengandung parameter pencarian "house", tekan URL berikut di browser: http://localhost/TestAPI/api/classifieds/get/house.

Kita harus mendapatkan respon berikut dalam browser:

Untuk melihat seluruh daftar rahasia, memukul URL tanpa parameter: http://localhost/TestAPI/api/classifieds/get/.

Anda harus melihat hasil sebagai berikut:

Kita dapat menambahkan sejumlah tindakan dan controller dengan cara yang sama seperti yang diinginkan oleh klien.

Negosiasi Konten

Hingga kini, kami telah melihat contoh API yang mengirim respons XML ke klien. Sekarang mari kita lihat tipe konten lain seperti JSON dan Image response, yang termasuk dalam topik Negosiasi Konten.

Spesifikasi HTTP (RFC 2616) mendefinisikan negosiasi konten sebagai “proses pemilihan representasi terbaik untuk respons yang diberikan ketika ada banyak representasi yang tersedia." Berkat fitur Negosiasi Konten API Web, klien dapat memberi tahu layanan API Web format konten apa yang diterima, dan API Web dapat melayani klien dengan format yang sama secara otomatis, asalkan formatnya dikonfigurasikan di Web API.

Meminta Format JSON

Header HTTP Accept digunakan untuk menentukan jenis media yang dapat diterima oleh
klien untuk tanggapan. Untuk XML, nilai yang ditetapkan sebagai "application/xml" dan JSON "application/json".

Untuk menguji API kami dengan header Terima HTTP, kami dapat menggunakan ekstensi yang tersedia untuk browser yang memungkinkan kami membuat permintaan HTTP khusus.

Di sini, saya menggunakan ekstensi bernama HTTP Tool yang tersedia untuk Mozilla Firefox untuk membuat header Terima yang menetapkan JSON sebagai jenis respons.

Seperti yang dapat Anda lihat dari gambar, respon yang sedang diterima adalah dalam format JSON.

File Gambar sebagai Respons

Terakhir, mari kita lihat bagaimana kita dapat mengirim file gambar sebagai respons melalui Web API.

Mari buat folder bernama Images dan tambahkan gambar yang disebut "default.jpg" di dalamnya, dan kemudian tambahkan metode Tindakan berikut di dalam ClassifiedsController kami.

public HttpResponseMessage GetImage()
        {
            byte[] bytes = System.IO.File
                           .ReadAllBytes
                           (
                                HttpContext.Current.Server
                                .MapPath("~/Images/default.jpg")
                           );
            
            var result = new HttpResponseMessage(HttpStatusCode.OK);

            result.Content = new ByteArrayContent(bytes);

            result.Content.Headers.ContentType = new MediaTypeHeaderValue("image/png");
            return result;
        }

Juga, ini dua namespaces harus disertakan: System.Web, System.Web.Http.

Di sini kita membuat respons HTTP menggunakan kelas HttpResponseMessage dan mengatur byte gambar sebagai konten respons. Kami juga mengatur header Content-Type ke "image/png".

Sekarang, jika kami menyebut tindakan ini di browser kami, Web API akan mengirimkan gambar default.jpg kami sebagai respons: http://localhost/TestAPI/api/classifieds/Getimage/.

Kesimpulan

Dalam tutorial ini, kami melihat bagaimana ASP.NET Web API dapat dengan mudah dibuat dan diekspos kepada klien sebagai metode Aksi Pengontrol MVC. Kami melihat sistem perutean default dan khusus, menciptakan struktur dasar Layanan API aplikasi bisnis waktu nyata, dan juga melihat berbagai jenis respons.

Dan jika Anda mencari beberapa utilitas tambahan untuk dibeli, ditinjau, atau digunakan, lihat tawaran .NET di CodeCanyon.

Saya harap Anda menikmati tutorial ini dan bermanfaat untuk membuat API Web Anda untuk perangkat seluler. Terima kasih!