api 버전의 필요성과 방법 논의

[nayonsoso]

api 관리를 하면 좋을 이유들이 생겨서 논의를 발의해봅니다.

1/ 무중단을 생각한다면 버전관리는 필수
새롭게 배포가 되어도 사용자가 이용하는데에 불편함이 없는 서비스를 목표로 해면 좋겠습니다.
사실 사용자들을 위한다는 것도 있지만, 무중단이라는 모래주머니를 달아야 우리 팀이 더 튼튼한 웹앱을 만들 수 있을 것 같기도 해요🌞
그런데 제가 전에 말한것처럼 '저희 프로젝트에서는 그냥 타이밍 맞춰서 하면 되지 않을까요?'가 더 이상 통하지 않게 될수도 있을 것 같습니다.
무중단으로 서버 / 프론트가 각자 빠르게 배포가 되고 있는 상황에서는 그 싱크를 맞추기가 더 어려울 것 같아요😭

2/ '앱'이라는 새로운 클라이언트의 특성
사용자가 항상 최신버전을 마주한다는 웹과 달리, 앱은 낮은 버전에서도 api를 호출하는 경우가 많습니다.
메이저 버전 배포라면 '반드시 업데이트를 해야 이용가능하다'는 설정을 할 수 있을것이지만,
오타 수정과 같은 마이너 버전의 배포까지 업데이트를 강제하게 할 순 없는 노릇이니깐요..😓
이런 앱의 특성 상 클라이언트 - 서버의 api 명세가 맞지 않게 될 위험이 더 커집니다.

그래서 api 버전을 도입하면 좋겠습니다!
이 디스커션에서 관련 논의를 해봐요~

[Gyuhyeok99]

저도 API버전 관리는 필요하다고 생각합니다!

API 버전 관리 도입할 때 최대한 변경 없이 자연스럽게 적용하는 게 좋다고 생각해요!
그래서 저는 메이저 버전을 URL에 붙이는 방식으로 제안드려봅니다..!

예시: POST /api/v1/users → 기존 버전
{ "username": "test_user", "email": "te**@example.com" }
만약에 기존 API에 호환성 깨지는 변화가 생기면 v2로 올립니다
예시: POST /api/v2/users (응답 형식이나 기능이 바뀌었을 때)
{ "username": "test_user", "contact": "te**@example.com" } }
그리고 새로운 기능 추가의 경우에는 메이저 버전은 그대로 두고, 마이너 버전만 올려서 내부적으로 구분하면 좋을 것 같아요.

예시:

POST /api/v1/users/details → 새 기능 추가 (내부 버전: v1.1.0)
오타나 버그 수정 같은 경우에는 패치 버전만 올리면 될 것 같아요.

예시:

POST /api/v1/users/details → 오타 수정 (내부 버전: v1.1.1)

그리고 메이저 버전이 변경될 때, 구버전도 일정 기간 유지하면 사용자에게 업데이트를 강제하지 않아도 안정적으로 이전할 수 있을 것 같습니다.
물론, 계속 유지할 수는 없으니 일정 기간 후에는 구버전 종료도 필요할 것 같아요.
(이 부분은 유지 기간을 정하면 좋을 것 같습니다!)

이렇게 하면 기존 서비스에 영향 없이 깔끔하게 버전 관리할 수 있을 것 같아요!

다른 의견 있으시면 자유롭게 공유해 주세요!
지금은 API별 버전 관리 방식인데, 혹시 다른 방식도 같이 이야기해보면 좋을 것 같습니다!

추가로 얼마전에 처음 알게된 깃허브 릴리즈 기능인데

릴리즈 pr 작성시 제목명을 저렇게 컨벤션 맞추면 자동으로 각 버전마다 바뀐 내용 기록할 수 있더라구요! 알고계실수도 있긴 한데 저는 신기했어서 공유드립니다 ㅎㅎ..

[nayonsoso]

배포 기능은 꼭 적용해봐요! ㅎㅎ 좋네요

[wibaek]

저도 좋은 것 같습니다~

추가적으로 최초로 v1 api를 추가할 때, 기존에 논의되었던 naming 통일도 같이 진행했으면 좋겠습니다. kebab-case 적용이라던지요.

또한 api 경로중 리소스를 plural로 표현 하는 것도 고려해보았으면 합니다.
https://stackoverflow.com/questions/6845772/should-i-use-singular-or-plural-name-convention-for-rest-resources

[nayonsoso]

의견 주셔서 감사합니다☺️☺️☺️

@Gyuhyeok99
규혁님이 말씀하신 것처럼 메이저 버전을 나타내면 될 것 같습니다.
그리고 우리 서비스 특성 상 6개월마다 한번씩 큰 변경이 있으니, 이전 버전 api 는 다음 6개월간 지원하는식으로 가도 좋을 것 같아요~

@wibaek
위백님이 말씀하신것처럼 케밥케이스 / 복수형 적용을 하려다보니, 아쉬운 uri 들이 몇군데 보이네요.. 😞
이것들도 한번에 싹 수정해보겠습니다.!

그런데 api 버전을 적용할 시점은 좀 뒤가 되어야 할 것 같아요!
당분간은 변경되는 api 들이 많을 것 같은데, 일일이 버전을 올리면 관리가 많이 복잡해질거라서..😱
기존 api 전체적으로 수정 & 아직 구현 안된 api 구현(로그인/ 등록한 학점 목록 조회 등)이 완료되고나서
앱 출시 전까지 v1 적용해봐도 괜찮을까요?

[wibaek]

넵 좋은 것 같습니다~

[Gyuhyeok99]

좋습니다!