옮긴이 노트 여러분이 이해하기 쉽도록 API 유연성과 관련해서 재미있는 예시를 하나 들어 볼게요.

백엔드 서버의 API 엔드포인트를 설계할 때 ‘v1’로 시작하는 경우가 있습니다. 예를 들어 ‘/api/v1/users’ 같은 방식이지요. 이렇게 엔드포인트에 버전을 부여하는 것은 바로 하위 호환성을 보장하기 위해서입니다. 다음 과정을 살펴보고 얼마나 공감하는지 확인해 보세요.

1. 초기 API를 v1 엔드포인트로 배포한다

예를 들어 사용자 목록을 불러오는 API를 처음에 /api/v1/users로 설정했다고 가정해 봅시다.

2. 새로운 요구 사항에 맞추어 v2 엔드포인트를 추가한다

시간이 지나면서 API 개선이 필요할 때, 기존 v1을 그대로 유지하면서 v2 엔드포인트를 만들어 새로운 데이터 구조나 기능을 추가합니다. 예를 들어 사용자 정보를 제공하는 방식은 같지만 데이터 구조가 다르다고 가정해 볼 수 있습니다. 사용자 이름을 name에서 user: { name }으로 수정했다거나 하는 식으로 말이죠.