API Versiyonlama – Spring Framework 7

Bu yazıda, Spring Framework 7.0 ve Spring Boot 4 ile birlikte gelen yeni API versiyonlama özelliğini detaylı bir şekilde inceleyeceğiz.

API Versiyonlama

Canlı ortamda çalışan projelerimiz, sürekli gelişim ve değişim ihtiyacı duyar. API’lerimizden gelen istekler ve verilen cevaplar zamanla değişime uğrar. Bu değişiklikleri yaparken backwards compatibility (geriye dönük uyumluluk) sağlamak kritik önem taşır.

Geleneksel Versiyonlama Yöntemi

Spring Framework’ün önceki versiyonlarında, API versiyonlamasını genellikle URL path’inde tanımlanır

@GetMapping(path = "/students/list"/v1/…")Code language: CSS (css)

Bu Spring Framework 7 ve Sprint Boot 4’te versiyonlama yontemi degisiyor.

Spring Framework 7.0’ın Getirdiği Yenilik

Spring Framework 7.0 ile birlikte, topluluk tarafından en çok istenen özelliklerden biri geldi. Artık API tanımlamalarımıza version attribute’ü eklenerek, versiyonlamayı daha standart ve yönetilebilir bir şekilde yapabiliyoruz.

  @GetMapping(path = "/students/list", version = "1.1")Code language: CSS (css)

Örnek Uygulama

application.propertis Konfigürasyonu

İlk olarak, application.properties dosyamızda versiyonlama ayarlarını yapılandıralım:

spring.mvc.apiversion.default=1.0.0
spring.mvc.apiversion.use.header=API-Version
spring.mvc.apiversion.supported=1.0,2.0,3.0Code language: PHP (php)

• spring.mvc.apiversion.default: Versiyon belirtilmediğinde kullanılacak varsayılan versiyondur.
• spring.mvc.apiversion.use.header: İstemcinin versiyon bilgisini göndereceği HTTP header adı
• spring.mvc.apiversion.supported: Desteklenen API versiyonları

RestController

/**
 * @author burakkutbay
 */
@RestController
@RequestMapping("/students")
public class StudentController {

    @GetMapping(path = "/list", version = "1.1")
    public String getStudents() {
        return "Hello students! version 1.1";
    }

    @GetMapping(path = "/list", version = "3.5")
    public String getStudentsV35() {
        return "Hello students! version 3.5";
    }

    @GetMapping(path = "/list", version = "3.7+")
    public String getStudentsV37() {
        return "Hello students! version 3.7+";
    }
}Code language: PHP (php)

version = "3.7+" şeklindeki kullanım, 3.7 ve üzeri tüm versiyonlar için bu endpoint’in kullanılacağını belirtir.

Client Tarafında İstek Gönderme

İstemci tarafından API’ye istek gönderirken, versiyon bilgisini HTTP header’da iletmemiz gerekiyor:

curl -H "API-Version: 1.1" http://localhost:8080/students/listCode language: JavaScript (javascript)

Hata Yönetimi

Desteklenmeyen bir API versiyonu ile istek gönderildiğinde, sistem otomatik olarak HTTP 400 (Bad Request) hatası döner.

Spring Framework 7.0, Spring Boot 4, API versiyonlama, REST API, header based versioning, backward compatibility, Java Spring, microservices versioning

İlgili Spring Boot içerikleri

• Spring Boot 4 HTTP Service Client
• Spring Boot ile Feature Flag yönetimi
• Spring Cloud Bus ile runtime konfigürasyon

İlgili Spring ve DevOps içerikleri

Spring Boot dersleri, Spring Cloud Bus, Testcontainers ve Docker notları ile ilgili rehberleri inceleyin.

İlgili Spring kaynakları

API tasarımını derinleştirmek için Spring Boot Dersleri merkez rehberine ve Spring Boot exception handling yazısına göz atabilirsiniz.