Cara menggunakan versi API di ASP.NET Core

Saat mengembangkan API, Anda harus mengingat satu hal: Perubahan tidak bisa dihindari. Ketika API Anda telah mencapai titik di mana Anda perlu menambahkan lebih banyak tanggung jawab, Anda harus mempertimbangkan untuk membuat versi API Anda. Oleh karena itu, Anda memerlukan strategi pembuatan versi.

Ada beberapa pendekatan untuk membuat versi API, dan masing-masing memiliki pro dan kontra. Artikel ini akan membahas tantangan pembuatan versi API dan bagaimana Anda dapat bekerja dengan paket Versi ASP.NET Core MVC Microsoft ke versi RESTful API yang dibangun di ASP.NET Core. Anda dapat membaca lebih lanjut tentang versi API Web di artikel saya sebelumnya di sini. 

Buat proyek API ASP.NET Core 3.1

Pertama, mari buat proyek ASP.NET Core di Visual Studio. Dengan asumsi Visual Studio 2019 diinstal di sistem Anda, ikuti langkah-langkah yang diuraikan di bawah ini untuk membuat proyek ASP.NET Core baru di Visual Studio.

  1. Luncurkan Visual Studio IDE.
  2. Klik "Buat proyek baru".
  3. Di jendela "Buat proyek baru", pilih "Aplikasi Web Inti ASP.NET" dari daftar templat yang ditampilkan.
  4. Klik Next.
  5. Di jendela "Configure your new project" yang ditampilkan berikutnya, tentukan nama dan lokasi untuk proyek baru tersebut.
  6. Klik Buat.
  7. Di jendela "Buat Aplikasi Web ASP.NET Core Baru", pilih .NET Core sebagai runtime dan ASP.NET Core 3.1 (atau yang lebih baru) dari daftar drop-down di bagian atas. Saya akan menggunakan ASP.NET Core 3.1 di sini.
  8. Pilih "API" sebagai template proyek untuk membuat aplikasi ASP.NET Core API baru. 
  9. Pastikan kotak centang "Aktifkan Dukungan Docker" dan "Konfigurasi untuk HTTPS" tidak dicentang karena kami tidak akan menggunakan fitur tersebut di sini.
  10. Pastikan Autentikasi disetel sebagai "Tanpa Autentikasi" karena kami juga tidak akan menggunakan autentikasi.
  11. Klik Buat. 

Ini akan membuat proyek ASP.NET Core API baru di Visual Studio. Pilih folder solusi Controllers di jendela Solution Explorer dan klik “Add -> Controller…” untuk membuat controller baru bernama DefaultController.

Ganti kode sumber kelas DefaultController dengan kode berikut.

    [Rute ("api / [controller]")]

    [ApiController]

    kelas publik DefaultController: ControllerBase

    {

        string [] penulis = string baru []

        {"Joydip Kanjilal", "Steve Smith", "Stephen Jones"};

        [HttpGet]

        publik IEnumerable Get ()

        {

            penulis kembali;

        }

    }

Kami akan menggunakan pengontrol ini di bagian selanjutnya dari artikel ini.

Untuk menerapkan versi API di ASP.NET Core, Anda perlu melakukan hal berikut:

  1. Instal paket Versi ASP.NET Core MVC.
  2. Konfigurasi versi API di kelas Startup.
  3. Beri anotasi pada pengontrol dan tindakan dengan atribut yang sesuai.

Instal paket Versi ASP.NET Core MVC

ASP.NET Core menyediakan dukungan untuk pembuatan versi API out-of-the-box. Untuk memanfaatkan versi API, yang perlu Anda lakukan hanyalah menginstal paket Microsoft.AspNetCore.Mvc.Versioning dari NuGet. Anda dapat melakukan ini baik melalui manajer paket NuGet di dalam Visual Studio 2019 IDE, atau dengan menjalankan perintah berikut di konsol manajer paket NuGet:

Instal-Paket Microsoft.AspNetCore.Mvc.Versioning

Perhatikan bahwa jika Anda menggunakan ASP.NET Web API, Anda harus menambahkan paket Microsoft.AspNet.WebApi.Versioning.

Konfigurasi versi API di ASP.NET Core

Sekarang paket yang diperlukan untuk membuat versi API Anda telah diinstal di proyek Anda, Anda dapat mengonfigurasi pembuatan versi API di metode ConfigureServices pada kelas Startup. Potongan kode berikut menggambarkan bagaimana hal ini dapat dicapai.

public void ConfigureServices (layanan IServiceCollection)

{

  services.AddControllers ();

  services.AddApiVersioning ();

}

Saat Anda membuat permintaan Get ke API Anda, Anda akan disajikan dengan kesalahan yang ditunjukkan pada Gambar 1.

Untuk mengatasi kesalahan ini, Anda dapat menentukan versi default saat menambahkan layanan pembuatan versi API ke penampung. Anda mungkin juga ingin menggunakan versi default jika versi tidak ditentukan dalam permintaan. Cuplikan kode berikut menunjukkan bagaimana Anda dapat menyetel versi default sebagai 1.0 menggunakan properti AssumeDefaultVersionWhenUnspecified jika informasi versi tidak tersedia dalam permintaan.

services.AddApiVersioning (config =>

{

   config.DefaultApiVersion = ApiVersion baru (1, 0);

   config.AssumeDefaultVersionWhenUnspecified = true;

});

Perhatikan bagaimana versi mayor dan versi minor diteruskan ke konstruktor kelas ApiVersion pada saat menetapkan versi default. Properti AssumeDefaultVersionWhenUnspecified bisa menampung nilai benar atau salah. Jika benar, versi default yang ditentukan saat mengonfigurasi versi API akan digunakan jika tidak ada informasi versi yang tersedia.

Kode sumber lengkap dari metode ConfigureServices diberikan di bawah ini untuk referensi Anda.

public void ConfigureServices (layanan IServiceCollection)

{

    services.AddControllers ();

    services.AddApiVersioning (config =>

    {

         config.DefaultApiVersion = ApiVersion baru (1, 0);

         config.AssumeDefaultVersionWhenUnspecified = true;

    });

}

Karena Anda belum menentukan informasi versi apa pun, semua titik akhir akan memiliki versi default 1.0.

Laporkan semua versi API Anda yang didukung

Anda mungkin ingin memberi tahu klien API semua versi yang didukung. Untuk melakukan ini, Anda harus memanfaatkan properti ReportApiVersions seperti yang ditunjukkan dalam cuplikan kode yang diberikan di bawah ini.

services.AddApiVersioning (config =>

{

  config.DefaultApiVersion = ApiVersion baru (1, 0);

  config.AssumeDefaultVersionWhenUnspecified = true;

  config.ReportApiVersions = true;

});

Gunakan versi dalam metode pengontrol dan tindakan

Sekarang mari tambahkan beberapa versi yang didukung ke pengontrol kami menggunakan atribut seperti yang ditunjukkan pada cuplikan kode yang diberikan di bawah ini.

    [Rute ("api / [controller]")]

    [ApiController]

    [ApiVersion ("1.0")]

    [ApiVersion ("1.1")]

    [ApiVersion ("2.0")]

    kelas publik DefaultController: ControllerBase

    {

        string [] penulis = string baru []

        {"Joydip Kanjilal", "Steve Smith", "Anand John"};

        [HttpGet]

        publik IEnumerable Get ()

        {

            penulis kembali;

        }

    }

Saat Anda membuat permintaan Dapatkan dari klien HTTP seperti Postman, berikut cara laporan versinya.

Anda juga dapat melaporkan versi yang tidak berlaku lagi. Untuk melakukan ini, Anda harus meneruskan parameter tambahan ke metode ApiVersion seperti yang ditunjukkan dalam cuplikan kode yang diberikan di bawah ini.

[ApiVersion ("1.0", Deprecated = true)]

Memetakan ke versi tertentu dari metode tindakan

Ada atribut penting lainnya bernama MapToApiVersion. Anda dapat menggunakannya untuk memetakan ke versi tertentu dari metode tindakan. Cuplikan kode berikut menunjukkan bagaimana hal ini dapat dilakukan.

[HttpGet ("{id}")]

[MapToApiVersion ("2.0")]

string publik Dapatkan (int id)

{

   penulis kembali [id];

}

Contoh lengkap versi API di ASP.NET Core

Berikut adalah kode sumber lengkap DefaultController untuk referensi Anda.

[Rute ("api / [controller]")]

[ApiController]

[ApiVersion ("1.0")]

[ApiVersion ("1.1")]

[ApiVersion ("2.0")]

kelas publik DefaultController: ControllerBase

{

  string [] penulis = string baru []

  {"Joydip Kanjilal", "Steve Smith", "Stephen Jones"};

  [HttpGet]

  publik IEnumerable Get ()

  {

      penulis kembali;

  }

  [HttpGet ("{id}")]

  [MapToApiVersion ("2.0")]

  string publik Dapatkan (int id)

  {

     penulis kembali [id];

  }

}

Strategi versi API di ASP.NET Core

Ada beberapa cara untuk membuat versi API Anda di ASP.NET Core. Di bagian ini kita akan membahasnya masing-masing.

Meneruskan informasi versi sebagai parameter QueryString

Dalam kasus ini, Anda biasanya akan meneruskan informasi versi sebagai bagian dari string kueri seperti yang ditunjukkan pada URL yang diberikan di bawah ini.

//localhost:25718/api/default?api-version=1.0

Meneruskan informasi versi di header HTTP

Jika Anda ingin meneruskan informasi versi di header HTTP, Anda harus menyiapkannya di metode ConfigureServices seperti yang ditunjukkan dalam cuplikan kode yang diberikan di bawah ini.

services.AddApiVersioning (config =>

{

   config.DefaultApiVersion = ApiVersion baru (1, 0);

   config.AssumeDefaultVersionWhenUnspecified = true;

   config.ReportApiVersions = true;

   config.ApiVersionReader = HeaderApiVersionReader baru ("api-version");

});

Setelah ini disiapkan, Anda dapat menjalankan metode tindakan yang berkaitan dengan versi API tertentu seperti yang ditunjukkan pada Gambar 3.

Berikan informasi versi di URL

Namun metode lain untuk meneruskan informasi versi adalah meneruskan informasi versi sebagai bagian dari rute. Ini adalah cara termudah untuk membuat versi API Anda, tetapi ada beberapa peringatan. Pertama, jika Anda menggunakan strategi ini, klien Anda harus memperbarui URL setiap kali versi baru API dirilis. Akibatnya, pendekatan ini melanggar prinsip dasar REST yang menyatakan bahwa URL sumber daya tertentu tidak boleh berubah.

Untuk mengimplementasikan strategi pembuatan versi ini, Anda harus menentukan informasi rute di pengontrol Anda seperti yang ditunjukkan di bawah ini.

[Route ("api / v {version: apiVersion} / [controller]")]

Daftar kode berikut menunjukkan bagaimana Anda dapat mengatur ini di kelas pengontrol Anda.

[Route ("api / v {version: apiVersion} / [controller]")]

[ApiController]

[ApiVersion ("1.0")]

[ApiVersion ("1.1")]

kelas publik DefaultController: ControllerBase

    {

        string [] penulis = string baru []

        {"Joydip Kanjilal", "Steve Smith", "Stephen Jones"};

        [HttpGet]

        publik IEnumerable Get ()

        {

            penulis kembali;

        }

        [HttpGet ("{id}")]

        [MapToApiVersion ("2.0")]

        string publik Dapatkan (int id)

        {

            penulis kembali [id];

        }

    }

Berikut adalah cara memanggil HTTP default untuk mendapatkan metode kelas DefaultController.

//localhost:25718/api/v1.0/default

Untuk memanggil metode HTTP GET lainnya, yaitu yang menerima parameter, tentukan yang berikut ini baik di browser web atau klien HTTP seperti Postman.

//localhost:25718/api/v2.0/default/1

Hentikan satu atau beberapa versi API Anda

Asumsikan Anda memiliki beberapa versi API, tetapi Anda ingin menghentikan satu atau beberapa versi. Anda dapat melakukannya dengan mudah - Anda hanya perlu menetapkan properti Deprecated dari kelas ApiVersionAttribute ke true seperti yang ditunjukkan dalam cuplikan kode yang diberikan di bawah ini.

[ApiController]

[ApiVersion ("1.0")]

[ApiVersion ("1.1", Deprecated = true)]

[ApiVersion ("2.0")]

kelas publik DefaultController: ControllerBase

{

     // Kode biasa

}

Versi API di ASP.NET Core sekarang mulus berkat pengenalan paket Microsoft.AspNetCore.Mvc.Versioning. Ada beberapa cara untuk membuat versi API Anda - Anda hanya perlu memutuskan strategi terbaik berdasarkan kebutuhan Anda. Anda juga dapat menggunakan beberapa skema pembuatan versi untuk API Anda. Ini menambah banyak fleksibilitas karena klien dapat memilih salah satu skema versi yang didukung.

Cara melakukan lebih banyak di ASP.NET Core:

  • Cara menggunakan Objek Transfer Data di ASP.NET Core 3.1
  • Cara menangani kesalahan 404 di ASP.NET Core MVC
  • Cara menggunakan injeksi ketergantungan dalam tindakan filter di ASP.NET Core 3.1
  • Cara menggunakan pola opsi di ASP.NET Core
  • Cara menggunakan perutean titik akhir di ASP.NET Core 3.0 MVC
  • Cara mengekspor data ke Excel di ASP.NET Core 3.0
  • Cara menggunakan LoggerMessage di ASP.NET Core 3.0
  • Cara mengirim email di ASP.NET Core
  • Cara memasukkan data ke SQL Server di ASP.NET Core
  • Cara menjadwalkan pekerjaan menggunakan Quartz.NET di ASP.NET Core
  • Cara mengembalikan data dari ASP.NET Core Web API
  • Cara memformat data respons di ASP.NET Core
  • Cara menggunakan ASP.NET Core Web API menggunakan RestSharp
  • Cara melakukan operasi asinkron menggunakan Dapper
  • Cara menggunakan tanda fitur di ASP.NET Core
  • Cara menggunakan atribut FromServices di ASP.NET Core
  • Cara bekerja dengan cookie di ASP.NET Core
  • Cara bekerja dengan file statis di ASP.NET Core
  • Cara menggunakan URL Rewriting Middleware di ASP.NET Core
  • Cara menerapkan pembatasan laju di ASP.NET Core
  • Cara menggunakan Azure Application Insights di ASP.NET Core
  • Menggunakan fitur NLog lanjutan di ASP.NET Core
  • Bagaimana menangani kesalahan di ASP.NET Web API
  • Bagaimana menerapkan penanganan pengecualian global di ASP.NET Core MVC
  • Bagaimana menangani nilai null di ASP.NET Core MVC
  • Versi lanjutan dalam ASP.NET Core Web API
  • Cara bekerja dengan layanan pekerja di ASP.NET Core
  • Cara menggunakan API Perlindungan Data di ASP.NET Core
  • Cara menggunakan middleware bersyarat di ASP.NET Core
  • Cara bekerja dengan status sesi di ASP.NET Core
  • Cara menulis pengontrol yang efisien di ASP.NET Core