API Versioning là một feature mới của Spring được hỗ trợ từ phiên bản 7, giúp chúng ta dễ dàng thêm version cho các RESTful API trong request header hoặc trong path parameter. Trong bài viết này, mình sẽ chia sẻ với các bạn cách enable API versioning cho ứng dụng sử dụng Spring framework và làm thế nào để thêm version trong request header cho các ứng dụng này các bạn nhé!
Đầu tiên, mình sẽ tạo mới một Spring Boot với Spring Web dependency để làm ví dụ, như sau:
Các bạn lưu ý là phải chọn Spring Boot version 4 trở đi! Chỉ có Spring Boot version 4 trở đi mới sử dụng Spring framework 7.
Mình sẽ tạo mới một Controller đơn giản để làm ví dụ, có nội dung như sau:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
package com.huongdanjava.springboot; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RestController; @RestController public class HelloController { @GetMapping("/hello") public String hello() { return """ { "message": "Hello from Huong Dan Java!" } """; } } |
Controller này hiện tại chỉ expose một endpoint đơn giản là “/hello” và hiện tại mình cũng chưa định nghĩa version cho nó, như các bạn thấy.
Để enable versioning cho endpoint này trong request header (nghĩa là khi request tới endpoint này, chúng ta phải truyền thông tin version trong header của request), các bạn có thể:
- Thêm một class configuration implement interface WebMvcConfigurer và override lại phương thức configureApiVersioning(), như sau:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
package com.huongdanjava.springboot; import org.springframework.context.annotation.Configuration; import org.springframework.web.servlet.config.annotation.ApiVersionConfigurer; import org.springframework.web.servlet.config.annotation.WebMvcConfigurer; @Configuration public class WebConfig implements WebMvcConfigurer { @Override public void configureApiVersioning(ApiVersionConfigurer configurer) { configurer.useRequestHeader("X-Api-Version") .addSupportedVersions("1"); } } |
- Hoặc các bạn cũng có thể sử dụng property như sau:
|
1 2 3 4 5 6 |
spring: mvc: apiversion: use: header: X-API-Version supported: 1 |
Ở đây, mình đang cấu hình sử dụng “X-Api-Version” là tên của request header để truyền version cho các endpoint.
Phương thức addSupportedVersions() dùng để chỉ định các version mặc định cho những endpoint mà chúng ta không định nghĩa version.
Lúc này nếu mình chạy ứng dụng ví dụ và request tới endpoint “/hello” mà không truyền version, mình sẽ nhận kết quả “Bad Request” như sau:
Bởi vì mình đã enable versioning support nên chúng ta phải truyền request header “X-Api-Version” các bạn nhé!
Kết quả khi mình truyền request header “X-Api-Version” như sau:
Để chỉ định version cho một endpoint bất kỳ, các bạn có thể sử dụng thuộc tính version của các annotation @GetMapping, @PostMapping, …. Ví dụ như sau:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 |
package com.huongdanjava.springboot; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RestController; @RestController public class HelloController { @GetMapping("/hello") public String hello() { return """ { "message": "Hello from Huong Dan Java!" } """; } @GetMapping(value = "/hello", version = "1.1") public String hello1_1() { return """ { "message": "Hello from Huong Dan Java! V1.1" } """; } } |
Lúc này thì giá trị của thuộc tính version sẽ được gán vào giá trị của request header, và mình có thể request tới endpoint với version 1.1 như sau:
