API Versioning 기준

[rlajm1203]

배경

리크루트 플랫폼이 26기 신입모집 때부터 사용되어, 현재까지 사용되고 있습니다.
그 동안 많은 유지보수를 거쳐왔고, API 명세부터 서버 내부 로직, 데이터베이스 구조 등 많은 수정사항이 있었습니다.

그 중 API 가 변경되었을 때, API 버전 관리는 어떻게 수행해야 할지에 대해서 논의해보고자 합니다.

API Versioning 해야하는지 의문이 드는 API 들

현재 swagger 명세를 보시면, 모든 API URI에 /api/v1이 prefix 로 붙어있습니다. 이는 v2 로 바뀔 수 있다는 가능성을 나타냅니다.

이번 리크루트 플랫폼 유지보수 작업을 하면서 API의 버전을 그대로 유지해야 하는지, 버전 업을 해야 하는지에 관해 의문이 드는 API 들이 있었습니다.

버전 업 의문이 드는 API는 아래와 같습니다.

Columns 조회 API

• 기존
  • GET /api/v1/boards/navigations/{navigation-id}/columns
  • path variable : navigation-id
• 변경
  • Query String 으로 year 정보를 추가
• 참고
  • 28기 신입모집 때, 칸반보드 기수 별 조회 기능을 구현하였지만, 백엔드 내부적으로 불안정하게 구현이 되어 있어서 이번에 더 안정된 방법으로 구현

Columns 생성 API

• 기존 :
  • POST /api/v1/boards/navigations/{navigation-id}/columns
  • path variable : navigationId
  • query string : title
• 변경: path variable 은 그대로 유지,

  • year 정보를 추가하고 title 과 함께 Request Body 로 전송

    {
    	"title" : "",
    	"year" : 29
    }
    

Interviewers 조회 API

• 기존 :
  • GET /api/v1/interviewers?order=name
  • query string : order
• 변경 : Query String 으로, role 정보를 추가하여 특정 권한 이상의 면접관 리스트를 조회
  • 참고 : 이전 면접관들까지 조회되는 문제 수정

궁금증

위 API 들은 성능 향상을 위한 API 도 아니고, 응답 형식이 바뀐 API도 아닙니다.
이미 존재하던 API의 불편한 점 (사용자의 불편한 경험 , 개발자의 불편한 경험) 때문에 변경된 API 입니다.
이 API 들은 과연 v1 을 유지할지 또는 v2 라고 부를지, 어떤 기준으로 API 버전 관리를 해야하는지 감이 잡히지 않아 디스커션 남깁니다.. ( _ _ )

[Profile-exe]

Column 조회 API

Query String이 "필수"입력이라면 v2로 추가하는 것이 좋다고 생각합니다!
기존의 호환성이 고려되지 않은 새로운 로직이 필요하기 때문입니다.

Column 생성 API

요청 본문에 속성이 추가되는 것으로 API 명세가 바뀌기 때문에 v2로 추가하는 것이 좋다고 생각합니다!

Interviewers 조회 API

role이 필수가 아닌 상태로 사용하는 상황이 존재합니다 (관리자 페이지 면접관 관리)
따라서 v1이 적절할 것 같습니다

[2yunseong]

좋습니다 !
API 버저닝 하기 전에, FE팀에 노티 주세요.
레거시 상 ../api/v1까지 환경변수에 있는걸로 알고 있어서, 개선이 필요합니다.
@JNU-econovation/econorecruitefe

[rlajm1203]

네 알겠습니다!!
결정해서 최대한 빨리 전달하겠습니다~!