Pembuatan versi REST API adalah aspek penting dalam mempertahankan API yang sukses dan dirancang dengan baik. Dengan menyertakan nomor versi di URL atau header permintaan HTTP, pengembang dapat memastikan bahwa klien API menggunakan versi yang benar dan dapat membuat perubahan pada API tanpa merusak klien yang sudah ada. Ada beberapa pendekatan berbeda untuk membuat versi REST API, termasuk menggunakan nomor versi di URL, menggunakan header Accept, dan menggunakan header kustom. Pada artikel ini, kita akan mengeksplorasi berbagai pendekatan terhadap pembuatan versi REST API dan mendiskusikan pro dan kontra dari setiap pendekatan. Kami juga akan melihat beberapa praktik terbaik untuk mengimplementasikan versi REST API di proyek Anda sendiri.
Saat membangun REST API di .NET, pembuatan versi merupakan pertimbangan penting. Dengan menyertakan nomor versi di URL atau header permintaan HTTP, pengembang dapat memastikan bahwa klien API menggunakan versi yang benar dan dapat membuat perubahan pada API tanpa merusak klien yang sudah ada. Ada beberapa pendekatan berbeda untuk membuat versi REST API di .NET, termasuk menggunakan nomor versi di URL, menggunakan header Terima, dan menggunakan header khusus. Pada artikel ini, kita akan menjelajahi berbagai pendekatan untuk pembuatan versi REST API di .NET dan mendiskusikan pro dan kontra dari setiap pendekatan. Kami juga akan melihat beberapa praktik terbaik untuk mengimplementasikan versi REST API di proyek .NET Anda.
Salah satu pendekatan umum untuk pembuatan versi REST API di .NET adalah dengan menggunakan nomor versi di URL. Misalnya, URL untuk API versi 1 mungkin terlihat seperti ini:
https://www.example.com/api/v1/
Keuntungan menggunakan nomor versi di URL adalah mudah dipahami dan diterapkan. Ini juga memperjelas kepada klien API versi mana yang mereka gunakan. Namun, penggunaan nomor versi di URL dapat mempersulit dukungan beberapa versi API secara bersamaan. Hal ini juga dapat mempersulit perubahan pada API, karena perubahan apa pun yang merusak klien yang sudah ada akan memerlukan perubahan URL API.
Pendekatan lain untuk pembuatan versi REST API di .NET adalah dengan menggunakan header Accept. Hal ini memungkinkan klien API untuk menentukan versi API yang ingin mereka gunakan. Misalnya, klien mungkin mengirimkan permintaan seperti ini:
GET /api/products HTTP/1.1 Host: www.example.com Accept: application/vnd.example-v1+json ample-v1+json
Keuntungan menggunakan header Accept adalah mempermudah dukungan beberapa versi API secara bersamaan. Hal ini juga memungkinkan penyedia API untuk membuat perubahan pada API tanpa mengubah URL. Namun, penggunaan header Accept bisa jadi lebih rumit untuk diterapkan dan mungkin tidak seintuitif klien API.
Pendekatan ketiga untuk pembuatan versi REST API di .NET adalah header khusus. Hal ini memungkinkan penyedia API untuk menentukan versi API di header HTTP khusus, bukan di URL atau header Terima. Misalnya, penyedia API mungkin menentukan versi API seperti ini:
GET /api/products HTTP/1.1 Host: www.example.com X-API-Version: 1 HTTP/1.1 Host: www.example.com X-API-Version: 1
Keuntungan menggunakan header khusus adalah fleksibel dan memungkinkan penyedia API memilih skema versi terbaik untuk API mereka. Namun, penerapannya juga bisa lebih rumit dan mungkin tidak seintuitif klien API.
Siapkan versi API di .Net 6
Untuk menyiapkan versi API di .NET, Anda perlu menginstal dua paket NuGet:
Microsoft.AspNetCore.Mvc.VersioningMicrosoft.AspNetCore.Mvc.Versioning.ApiExplorer
Paket-paket ini masing-masing memberikan dukungan untuk mengimplementasikan pembuatan versi API dan menghasilkan metadata tentang API. Anda dapat menginstal kedua paket menggunakan perintah berikut:
dotnet add package Microsoft.AspNetCore.Mvc.Versioning dotnet add Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer
Setelah menginstal paket, Anda dapat menggunakannya untuk menambahkan informasi versi ke titik akhir URL API Anda atau ke header permintaan. Hal ini dapat membantu Anda mempertahankan kompatibilitas mundur dan mengelola beberapa versi API Anda. Metadata yang dihasilkan oleh paket ApiExplorer dapat berguna untuk menghasilkan dokumentasi interaktif atau untuk menguji titik akhir API.
Anda perlu menambahkan kode berikut ke Program.cs setelah menginstal paket.
builder.Services.AddApiVersioning(opt =>
{
opt.DefaultApiVersion = new ApiVersion(1, 0);
opt.AssumeDefaultVersionWhenUnspecified = true;
opt.ReportApiVersions = true;
opt.ApiVersionReader = ApiVersionReader.Combine(new UrlSegmentApiVersionReader(),
new HeaderApiVersionReader("x-api-version"),
new MediaTypeApiVersionReader("x-api-version"));
});
builder.Services.AddVersionedApiExplorer(setup =>
{
setup.GroupNameFormat = "'v'VVV";
setup.SubstituteApiVersionInUrl = true;
});
Sekarang kita telah menyiapkan versi API dan siap, mari kita coba menggunakannya untuk membuat versi pengontrol.
Buat 2 folder versi dan folder Controller dan buat 2 pengontrol pengguna.
Untuk mengimplementasikan pembuatan versi API di .NET, Anda dapat menggunakan atribut seperti Route untuk menentukan titik akhir URL atau header untuk mengakses berbagai versi API Anda. Misalnya, Anda dapat menggunakan atribut Route dengan parameter apiVersion untuk menentukan nomor versi di titik akhir URL, seperti ini:
[Route("api/v{version:apiVersion}/[controller]")]This will allow you to access different versions of your API using the version number in the URL.
Alternatifnya, Anda dapat menggunakan atribut Route tanpa parameter apiVersion untuk menentukan titik akhir default, dan menggunakan header x-api-version untuk menentukan versi API dalam permintaan. Misalnya:
[Route("api/[controller]")]
Dengan pendekatan ini, klien dapat menentukan versi API yang ingin mereka gunakan menggunakan header x-api-version dalam permintaan mereka. Ini bisa berguna jika Anda ingin mengizinkan klien mengakses versi API yang berbeda menggunakan titik akhir yang sama.
Di bawah v1 Folder Buat Pengontrol Pengguna
using Microsoft.AspNetCore.Mvc;
namespace WebApiVersioningTest.Controllers.V1;
[ApiController]
[Route("api/v{version:apiVersion}/[controller]")]
[Route("api/[controller]")]
[ApiVersion("1.0")]
public class UserController : ControllerBase
{
[MapToApiVersion("1.0")]
[HttpGet]
public IActionResult Get()
{
return Ok("V1");
}
}
Di bawah v2 Folder Buat pengontrol Pengguna V2:
using Microsoft.AspNetCore.Mvc;
namespace WebApiVersioningTest.Controllers.V2;
[ApiController]
[Route("api/v{version:apiVersion}/[controller]")]
[Route("api/[controller]")]
[ApiVersion("2.0")]
public class UserController : ControllerBase
{
[MapToApiVersion("2.0")]
[HttpGet]
public IActionResult Get()
{
return Ok("V2");
}
}
Konfigurasi Versi Swagger
Untuk mengonfigurasi Swagger agar berfungsi dengan versi API yang berbeda di .NET, Anda dapat mengimplementasikan antarmuka IConfigureNamedOptions<SwaggerGenOptions> dan menggunakannya untuk mendaftarkan setiap versi API dan mengidentifikasi versi default. Hal ini dapat dilakukan dengan membuat kelas ConfigureSwaggerOptions yang mengimplementasikan metode Configure dan antarmuka IConfigureNamedOptions<SwaggerGenOptions>, seperti ini:
public class ConfigureSwaggerOptions
: IConfigureNamedOptions<SwaggerGenOptions>
{
private readonly IApiVersionDescriptionProvider _provider;
public ConfigureSwaggerOptions(
IApiVersionDescriptionProvider provider)
{
_provider = provider;
}
/// <summary>
/// Configure each API discovered for Swagger Documentation
/// </summary>
/// <param name="options"></param>
public void Configure(SwaggerGenOptions options)
{
// add swagger document for every API version discovered
foreach (var description in _provider.ApiVersionDescriptions)
{
options.SwaggerDoc(
description.GroupName,
CreateVersionInfo(description));
}
}
/// <summary>
/// Configure Swagger Options. Inherited from the Interface
/// </summary>
/// <param name="name"></param>
/// <param name="options"></param>
public void Configure(string name, SwaggerGenOptions options)
{
Configure(options);
}
/// <summary>
/// Create information about the version of the API
/// </summary>
/// <param name="description"></param>
/// <returns>Information about the API</returns>
private OpenApiInfo CreateVersionInfo(
ApiVersionDescription desc)
{
var info = new OpenApiInfo()
{
Title = ".NET Core (.NET 6) Web API",
Version = desc.ApiVersion.ToString()
};
if (desc.IsDeprecated)
{
info.Description += " This API version has been deprecated. Please use one of the new APIs available from the explorer.";
}
return info;
}
}
Setelah membuat kelas ini, Anda dapat menambahkan kode berikut ke file Program.cs Anda untuk menggunakannya untuk mengonfigurasi Swagger:
// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
var apiVersionDescriptionProvider = app.Services.GetRequiredService<IApiVersionDescriptionProvider>();
app.UseSwagger();
app.UseSwaggerUI(options =>
{
foreach (var description in apiVersionDescriptionProvider.ApiVersionDescriptions)
{
options.SwaggerEndpoint($"/swagger/{description.GroupName}/swagger.json",
description.GroupName.ToUpperInvariant());
}
});
}
Setelah menerapkan kode ini, UI Swagger akan menampilkan dokumentasi untuk setiap versi API. Hal ini dapat berguna untuk memberikan informasi kepada konsumen API tentang berbagai versi API dan untuk menguji versi API yang berbeda.
Singkatnya, ada beberapa pendekatan berbeda untuk pembuatan versi REST API di .NET, masing-masing memiliki kelebihan dan kekurangannya sendiri. Pendekatan terbaik untuk situasi Anda akan bergantung pada persyaratan spesifik API Anda dan preferensi tim Anda. Penting untuk mempertimbangkan semua opsi dengan cermat dan memilih pendekatan yang paling sesuai dengan situasi Anda.
Kode lengkap untuk proyek ini dapat ditemukan di repositori berikut: https://github.com/saideldah/api-versioining-dot-net-6
