API 설계 시 버전을 명시하는 방법

 

API 설계 시 버전을 명시하는 방법은 크게 URL 기반, 헤더 기반, 쿼리 파라미터 기반으로 나뉘지만, URL 경로에 버전을 포함시키는 방식이 가장 널리 사용됩니다. 여기서는 URL 버전 방식(/v1/api/songs)을 기준으로 Spring Boot Controller 예시, 그리고 버전 업 시 네이밍 및 req/res 설계 변경 예시를 설명드릴게요.

---

✅ URL 기반 버전 관리 기본 예시

✅ /v1/api/songs 예시 – SongControllerV1

@RestController
@RequestMapping("/v1/api/songs")
public class SongControllerV1 {

    @GetMapping
    public List<SongResponseV1> getSongs() {
        // 간단한 예시
        return List.of(new SongResponseV1("로이킴", "내게 사랑이 뭐냐고 물어본다면"));
    }
}

@Data
@AllArgsConstructor
public class SongResponseV1 {
    private String artist;
    private String title;
}

---

✅ /v2/api/songs 예시 – SongControllerV2 (버전 변경된 설계)

버전 2에서는 예를 들어 곡의 ID 추가, 발매일 등 정보를 확장할 수 있습니다.

@RestController
@RequestMapping("/v2/api/songs")
public class SongControllerV2 {

    @GetMapping
    public List<SongResponseV2> getSongs() {
        return List.of(new SongResponseV2(1L, "로이킴", "내게 사랑이 뭐냐고 물어본다면", LocalDate.of(2010, 12, 9)));
    }
}

@Data
@AllArgsConstructor
public class SongResponseV2 {
    private Long id;
    private String artist;
    private String title;
    private LocalDate releaseDate;
}

---

🔁 Request 예시 변화

🔸 V1에서 POST 요청

POST /v1/api/songs
{
  "artist": "로이킴",
  "title": "내게 사랑이 뭐냐고 물어본다면"
}

🔸 V2에서는 releaseDate를 추가

POST /v2/api/songs
{
  "artist": "로이킴",
  "title": "내게 사랑이 뭐냐고 물어본다면",
  "releaseDate": "2010-12-09"
}

---

🧭 네이밍 전략 팁

요소	V1 네이밍	V2 네이밍
컨트롤러 클래스	SongControllerV1	SongControllerV2
DTO 클래스	SongResponseV1	SongResponseV2
엔드포인트	/v1/api/songs	/v2/api/songs

또는 DTO는 SongResponse, SongResponseV2 식으로 하여 V2만 접미사를 붙이는 것도 일반적입니다.

---

🧩 확장 고려사항

• v1, v2가 공존하는 동안은 각 버전의 명세와 유지보수가 필요합니다.
• Swagger(OpenAPI)는 다음과 같이 버전별로 그룹을 분리해 문서화할 수 있습니다:

.groupName("v1")
.pathsToMatch("/v1/**")

• 실제 운영 시에는 특정 기간 이후 v1 지원을 종료하고 리다이렉트하거나 에러 처리합니다.