API 요청 버전 관리는 기존 클라이언트에 영향을 주지 않으면서 API의 파괴적 변경(예: 구조 변경, 필드 이름 변경, 필드 제거, 필수 필드 추가)을 적절히 처리하기 위해 필수적입니다. 반면, 선택적 필드 추가나 필드를 선택적으로 변경하는 경우에는 버전 업이 필요하지 않습니다.
이러한 요청 버전 관리를 위해 다음과 같은 요구사항들이 고려되어야 합니다:
- OpenAPI 지원: API 문서화의 중요성을 강조하며, OpenAPI를 통해 API의 사용성을 높일 수 있습니다. ‘verquest’ 젬은 JSON Schema 기반의 OpenAPI 컴포넌트 생성을 지원하여 문서화의 복잡성을 줄입니다.
- DRY (Don’t Repeat Yourself): 각 버전마다 요청 정의를 반복하지 않고, 이전 버전과의 차이점만 정의함으로써 코드 중복을 최소화해야 합니다.
- 내부 구현 숨기기: 내부 모델 및 속성 명명 규칙과 외부 API 명명 규칙을 분리하여 API의 사용자 친화성을 높여야 합니다. ‘verquest’는
map옵션을 통해 외부 요청 구조를 내부 구조로 매핑하는 기능을 제공합니다. - 내부 오류 외부 구조로 매핑: 사용자에게 오류 발생 위치를 명확히 알려주기 위해 내부 오류 메시지를 외부 API 구조에 맞게 변환하는 기능의 필요성을 언급하며, ‘verquest’에서는 향후 지원할 기능으로 계획하고 있습니다.
저자가 직접 개발한 ‘verquest’ 젬은 위에 언급된 요구사항 대부분을 충족합니다.
- 스키마 정의: ‘verquest’는
Verquest::Base클래스를 상속받아 스키마를 정의하며,version블록을 통해 특정 버전의 스키마를 정의할 수 있습니다.field및objectDSL을 사용하여 JSON Schema를 쉽게 정의할 수 있으며,map옵션을 통해 외부/내부 구조 매핑을 지원합니다. - Rails에서의 사용 예시:
UsersController의create액션에서UserCreateRequest.process(params, version: params[:api_version])를 사용하여 요청 파라미터를 유효성 검사하고 내부 구조로 매핑하는 방법을 보여줍니다.Verquest::InvalidParamsError를 통해 유효하지 않은 파라미터에 대한 오류 응답을 처리할 수 있습니다. - 파괴적 변경 처리: 새로운 필수 필드 추가와 같은 파괴적 변경 발생 시,
version블록 내에서exclude_properties를 사용하여 이전 버전의 필드를 제외하고 새로운 버전에 맞게 재정의할 수 있습니다. ‘verquest’는 명시된 버전이 없을 경우 가장 가까운 이전 버전을 사용하는 “downgrading” 전략을 구현합니다. - OpenAPI 지원:
component_name,to_ref,to_schema와 같은 메서드를 제공하여 rswag 젬과 같은 도구를 활용한 OpenAPI 문서 생성을 돕습니다.