API 요청 버전 관리가 필요한 주된 이유는 파괴적인 변경 사항(예: 필드 구조 변경, 필드 이름 변경, 필드 제거, 필수 필드 추가 등)을 안전하게 처리하기 위함입니다. 반면, 새로운 선택적 필드 추가나 필드를 선택적으로 변경하는 경우는 버전 업데이트가 필요하지 않을 수 있습니다. 저자는 효과적인 요청 버전 관리를 위한 네 가지 핵심 요구사항을 제시합니다. 첫째, OpenAPI 지원을 통해 API를 문서화하고 다양한 도구에서 활용할 수 있어야 합니다. 둘째, DRY(Don’t Repeat Yourself) 원칙을 준수하여 각 버전별로 요청 정의를 반복하지 않고, 이전 버전과의 차이점만 정의하도록 합니다. 셋째, 내부 구현을 숨겨 모델이나 속성 이름을 내부 명명 규칙과 다르게 외부에 노출함으로써 API의 사용자 친화성을 높여야 합니다. 넷째, 내부 오류를 외부 구조에 맞게 매핑하여 사용자가 오류 발생 시 수정 지점을 쉽게 파악할 수 있도록 해야 합니다.
이러한 요구사항을 충족하기 위해 저자는 ‘verquest’라는 새로운 Ruby Gem을 개발했습니다. verquest는 오류 매핑 기능을 제외한 대부분의 요구사항을 충족하며, 향후 오류 매핑 기능 추가를 계획하고 있습니다. verquest Gem은 JSON 스키마를 쉽게 정의할 수 있는 DSL(Domain Specific Language)을 제공하여 OpenAPI 컴포넌트 생성 및 유효성 검사에 활용됩니다. 예를 들어, UserCreateRequest 클래스를 통해 사용자 생성 요청의 스키마를 정의하고, to_validation_schema 메서드를 통해 해당 스키마의 JSON 표현을 확인할 수 있습니다. 또한, map 키워드를 사용하여 외부 요청 구조를 내부 구조로 자동 매핑하는 기능을 제공합니다.
Rails 애플리케이션에서 verquest Gem은 컨트롤러에서 process 메서드를 사용하여 들어오는 매개변수를 JSON 스키마에 대해 유효성 검사하고 내부 구조로 매핑하는 데 활용됩니다. 유효하지 않은 매개변수가 제공될 경우 Verquest::InvalidParamsError 예외를 발생시키며, 상세한 오류 정보를 포함합니다. 파괴적인 변경 사항을 처리하는 방식도 주목할 만합니다. 새로운 버전(예: ‘2025-08’)을 추가하고, 이전 버전(‘2025-06’)에서 선택적이었던 필드를 새 버전에서 필수로 변경하는 방식으로 버전 상속을 활용합니다. verquest는 정확한 버전이 없을 경우 가장 가까운 이전 버전을 사용하는 ‘다운그레이딩’ 전략을 구현하고 있습니다. 마지막으로, verquest는 component_name, to_ref, to_schema와 같은 메서드를 제공하여 rswag Gem과 같은 도구를 사용하여 OpenAPI 문서를 구축하는 데 도움을 줍니다.