URI naming 문의드려요.

Question

영한님, 안녕하세요. URI naming 관련해서 2가지 문의를 남기고 갈께요. 항상 바쁘시지만 고견을 구합니다. 1) API 버전 - 영한님, 수많은 강의에서 보면 API 에는 주로 V1, V2 같은 버전을 기록하시는 것 같던데 이번 강의에서는 버전에 대한 말씀은 없으시더라고요. 보통 버전을 URI 에 포함시키는게 좋은 지, 만약 포함시킨다면 버전의 위치는 어디가 가장 적합한지 알고 싶습니다. 2) 복잡한 쿼리 조회성 API naming - 현업에서는 검색조건이 다양하게 있고 결과도 UI Grid 에 다양한 컬럼이 있는 표 화면을 활용하는 케이스가 많은데요. (보통 API 에서 다수의 테이블을 조인하는 쿼리를 실행해서 출력하는) 이런 API는 사실 Main Resource 를 정하기 어려운 경우가 상당히 있는 것 같습니다. 이런 복잡한 쿼리를 통해 화면에 목록성 데이터를 출력하는 Get API 는 네이밍을 어떻게 잡는 게 좋을까요?

김영한 · Answer

안녕하세요. 아리마님 1. 여러가지 방안이 있는데요. 만약 버전이 필요하다면 저는 URL에 버전을 적용하는 것을 선호합니다. HTTP 헤더에 버전을 사용할 수도 있는데, 예를 들어서 HTTP 헤더에 넣게되면 이것을 누락했을 때 최신 버전을 사용하는 식으로 사용하는 경우가 있더라구요. 그런데 이렇게 되면, 향후 새로운 버전이 나왔을 때 과거 스펙이 다 깨지면서 문제가 발생할 수 있습니다. 그래서 가급적 명확하게 URL에 버전을 명시하는 것을 선호합니다. 그리고 모니터링하거나 이럴 때도 URL에 버전이 있으면 더 편리하더라구요. 그런데 이 부분은 다들 생각이 다를 것 같아서 참고만 해주세요. 추가로 실무에서는 버전 같은 것을 실수로라도 누락하지 않게 강제하는 것이 장애를 덜 발생하게 되더라구요. 그리고 필드가 추가되는 것 같은 작은 작은 변화에는 가급적 버전을 올리지 않습니다. 대신 이 API는 향후 필드가 추가될 수 있으니 사용하지 않는 필드는 무시해달라고 스펙에 명확히 명시하고 공유해야 합니다. 2. 이런 경우에는 URI Naming이 잘 맞지 않습니다. 그냥 그 API에 맞는 별도의 이름을 주는 것이 좋다 생각합니다. 감사합니다^^