API Versioning Rule

Versioning 필요

• api spec 변경
  • request, response model 변경
• bug fix
• enum 속성 추가/삭제

 

Versioning 방식

URI Path

• URI 에 version path 를 추가
• 직관적이고 테스트가 쉽다
• ex) http//domain/{version}/api-path
  • http://localhost:8080/v1/users/{id}
  • http://localhost:8080/v2/users/{id}

URL Parameter

• version 정보를 query paramter 로 정의
• URI Path 방식과 비슷하고, 동일한 URL을 사용 할 수 있다.
• ex) http//domain/api-path?version={version}
  • http://localhost:8080/users?version=1
  • http://localhost:8080/users?version=2

MediaType

• accept header 에 version 을 정의
• accept 정보로 요청분기 처리가 가능하고, 동일한 URL 사용이 가능하다.
• ex)
  • http://localhost:8080/users -headers[Accept=application/vnd.pfm.app-v1+json]
  • http://localhost:8080/users -headers[Accept=application/vnd.pfm.app-v2+json]

Custom Header

• request header 에 version 정보 속성을 추가
• MediaType과 대체로 비슷하고, 사용자가 원하는 속성이름으로 사용이 가능하다
• ex)
  • http://localhost:8080/users -headers=[lpfm-api-version=1]
  • http://localhost:8080/users -headers=[lpfm-api-version=2]

 

 

 

참고

• API Versioning Policy
• https://stackoverflow.com/questions/389169/best-practices-for-api-versioning
• https://hackernoon.com/restful-api-designing-guidelines-the-best-practices-60e1d954e7c9
• https://stackoverflow.com/questions/20198275/how-to-manage-rest-api-versioning-with-spring
• https://www.springboottutorial.com/spring-boot-versioning-for-rest-services
• https://github.com/augusto/restVersioning
• https://piotrminkowski.wordpress.com/2018/02/19/versioning-rest-api-with-spring-boot-and-swagger/
• https://medium.com/@DevChris01/springboot-api-versioning-fast-easy-c3ef2c87452f