RESTful API’yi sürüm yönetiminin en iyi yolu tartışma konusudur. Her yaklaşımın kendi artıları ve eksileri vardır. Bir REST API’sini sürüm yönetimi söz konusu olduğunda ‘herkese uyan tek bir çözüm’ yoktur.

Bu makalede, bazı sürüm yöntemlerinden birkaçı gösterilecektir.

Proje Oluşturma

Yeni bir .NET core web API projesi oluşturun. Microsoft.AspNetCore.Mvc.Versioning Nuget paketini projeye ekleyin.

Sonrasında Startup.cs içerisine aşağıdaki config ayarını ekliyoruz.

public void ConfigureServices(IServiceCollection services)
{
    .
    .
    .
    services.AddApiVersioning(config =>
    {
      // Varsayılan API Sürümü
      config.DefaultApiVersion = new ApiVersion(1, 0);
      // İstemci istekte API sürümünü belirtmediyse, varsayılan API sürüm numarası kullanma 
      config.AssumeDefaultVersionWhenUnspecified = true;
      // Belirli bir son nokta için desteklenen API sürümlerinin bilgisini verme
      config.ReportApiVersions = true;
    });
}

Örnek 1: Url Sorgu Parametrelerini Kullanma

Microsoft.AspNetCore.Mvc.Versioning paketi tarafından sağlanan varsayılan sürüm oluşturma şeması api-version sorgu parametresini kullanır.

Sorgu dizesi kullanarak bir API’yi sürümlendirmek, istemcilerin gereksinimlerine göre sürüm numarasını açıkça belirtmesine olanak tanır. Diğer sürüm oluşturma stratejilerinin aksine, istemcilerin her istekte API sürüm bilgilerini içermesi gerekmez. Api sürümü sorgu dizesi istemci tarafından belirtilmezse, varsayılan sürüm dolaylı olarak istenir.

[Route("api/[controller]")]
[ApiController]
[ApiVersion("1")]
[ApiVersion("2")]
public class ValuesController : ControllerBase
{
  [HttpGet]
  [MapToApiVersion("1")]
  public ActionResult<IEnumerable<string>> GetV1()
  {
      return new string[] { "Sürüm 1 => value1", "Sürüm 1 => value2" };
  }

  [HttpGet]
  [MapToApiVersion("2")]
  public ActionResult<IEnumerable<string>> GetV2()
  {
      return new string[] { "Sürüm 2 => value 1", "Sürüm 2 => value2 " };
  }
}
https://siteadres/api/values?api-version=1
https://siteadres/api/values?api-version=2

Örnek 2: URL sürüm oluşturma şemasını kullanma

Doğrudan URL yolunda bir sürüm numarası kullanmak, bir API’yi sürümlendirmenin en basit yollarından biridir. URL yolu sürüm oluşturma yaklaşımı, URL’nin kendisindeki sürüm numarasını açıkça belirttiği için daha görünürdür. Ancak bu yaklaşım, istemcilerin her yeni API sürümü olduğunda uygulamalarında URL’lerini değiştirmelerini zorunlu kılar. Ayrıca, API sürümünü URL’nin içine gömmek, her URL’nin belirli bir kaynağı temsil etmesi ve kaynak URL’sinin zaman içinde değişmemesi gerektiğini belirten REST API’nin temel bir ilkesini ihlal edecektir. Bu yaklaşım, her yeni API sürümünün büyük değişikliklere sahip olduğu durumlarda daha uygundur.

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

.Net Core Attribute Routing yardımı ile versiyon numarasını url üzerinden direkt olarak alabiliriz.

[Route("api/v{version:apiVersion}/[controller]")]
[ApiController]
[ApiVersion("1")]
[ApiVersion("2")]
public class ValuesController : ControllerBase
{
    [HttpGet]
    [MapToApiVersion("1")]
    public ActionResult<IEnumerable<string>> GetV1()
    {
        return new string[] { "Sürüm 1 => value1", "Sürüm 1 => value2" };
    }

    [HttpGet]
    [MapToApiVersion("2")]
    public ActionResult<IEnumerable<string>> GetV2()
    {
        return new string[] { "Sürüm 2 => value 1", "Sürüm 2 => value2 " };
    }
}
https://siteadres/api/v1/values/

Örnek 3: İstek Üstbilgilerini Kullanma

Bir API’yi sürümlendirmeye yönelik başka bir yaklaşım, üstbilgi değerinin API sürümünü belirlediği istek üstbilgilerini kullanmaktır. Birçok geliştirici bu yaklaşımı savunmaktadır, çünkü URL yolu parametresi ve sorgu dizesi yaklaşımından farklı olarak, istek üstbilgisini kullanmak istemci tarafındaki URL’lerle uğraşmayı gerektirmez. Sürüm oluşturma için istek başlıklarını kullanmanın dezavantajı, sürüm oluşturma seçeneğinin ilk bakışta istemci tarafından açıkça görülememesidir.

Varsayılan olarak, Microsoft.AspNetCore.Mvc.Versioning paketi, istekte API sürümünü belirtmek için sorgu parametresi stratejisini kullanır. API Sürümü’nü, bir Sürüm Okuyucusu kullanarak istek başlıklarını bir sürüm stratejisi olarak kullanacak şekilde yapılandırın. ApiVersionReader , sürümleme şemasını belirtmek için kullanılır, bu sınıf isteği analiz eder ve hangi sürümün talep edildiğini belirler. Belirtilmezse, varsayılan sürüm okuyucu şeması QueryStringApiVersionReader’dır , bu nedenle daha önce api sürümü sorgu parametrelerini kullanarak v1 isteğinde bulunabildik.

Sürüm okuyucunun HeaderApiVersionReader olarak değiştirilmesi, istemcilerin sorgulama parametreleri yerine istek üstbilgisini kullanarak sürüm bilgilerini göndermesini sağlar. API Sürümü, X sürümü üstbilgisinde istemci tarafından belirtilebilir . HeaderApiVersionReader() yöntemine parametre olarak iletilen “X sürümü” dizesinin, API sürüm bilgisi göndermek için kullanılan istek üstbilgisi için seçilen rasgele bir ad olduğunu unutmayın.

public void ConfigureServices(IServiceCollection services)
{
    .
    .
    .
    services.AddApiVersioning(config =>
    {
        // Varsayılan API Sürümü
        config.DefaultApiVersion = new ApiVersion(1, 0);
        // İstemci istekte API sürümünü belirtmediyse, varsayılan API sürüm numarası kullanma 
        config.AssumeDefaultVersionWhenUnspecified = true;
        // Belirli bir son nokta için desteklenen API sürümlerinin bilgisini verme
        config.ReportApiVersions = true;
        // İstemci X sürümü üstbilgisini kullanarak belirli sürümü ister
        config.ApiVersionReader = new HeaderApiVersionReader("X-version");
    });
}
[Route("api/[controller]")]
[ApiController]
[ApiVersion("1")]
[ApiVersion("2")]
public class ValuesController : ControllerBase
{
    [HttpGet]
    [MapToApiVersion("1")]
    public ActionResult<IEnumerable<string>> GetV1()
    {
        return new string[] { "Sürüm 1 => value1", "Sürüm 1 => value2" };
    }

    [HttpGet]
    [MapToApiVersion("2")]
    public ActionResult<IEnumerable<string>> GetV2()
    {
        return new string[] { "Sürüm 2 => value 1", "Sürüm 2 => value2 " };
    }
}
Image for post

CEVAP VER

Please enter your comment!
Please enter your name here