API Gateway Transformation이란
API Gateway Transformation은 클라이언트와 백엔드 서비스 간 통신 양 끝에서 요청 및 응답의 형식·내용을 수정하는 프로세스입니다. 게이트웨이가 클라이언트 요청을 수신한 후 백엔드 서비스가 이해할 수 있는 형식으로 변환하거나, 백엔드 응답을 클라이언트가 기대하는 형식으로 변환합니다.
주요 변환 형태와 구현 전략
헤더 변환은 가장 가볍고 자주 사용되는 형태입니다. 예를 들어 요청 ID 주입(X-Request-ID), 인증 정보 추가, 호출자 IP 기록(X-Forwarded-For) 등이 포함됩니다. 헤더 변환은 바디 파싱이 필요 없어 오버헤드가 거의 없습니다.
바디 변환은 더 복잡합니다. JSON 필드 이름 변경(camelCase ↔ snake_case), 민감한 데이터 제거, 페이로드 구조 재편성 등을 포함합니다. Velocity Template Language(VTL) 또는 JSONPath를 이용한 매핑 템플릿 방식과 선언적 설정 방식(필드 추가/제거/이름 변경)이 있습니다. 바디 변환은 파싱·직렬화 오버헤드로 인해 처리량에 영향을 줄 수 있습니다.
프로토콜 변환은 REST ↔ gRPC, HTTP ↔ WebSocket 등의 변환으로 가장 복잡합니다. 이 경우 grpc-gateway나 Envoy 트랜스코더와 같은 전문 도구를 사용하는 것이 권장됩니다.
아키텍처상 핵심 이점과 주의점
게이트웨이에서 변환을 중앙화하면 여러 서비스에서 반복되는 로직을 제거할 수 있으며, 내부 API 진화 시 외부 계약을 깨지 않습니다. 또한 레거시 API 지원, 데이터 정규화, 내부 구현 상세사항 은폐 등이 가능합니다.
하지만 높은 처리량이 필요한 API의 경우 복잡한 바디 변환은 바이 바이 크기와 스크립트 복잡도에 비례한 지연을 초래할 수 있습니다. 또한 컨텍스트 변수는 원본 요청/응답에서만 추출되므로, 변환 과정에서 새로 생성된 값은 후속 정책 평가에 반영되지 않는 점을 주의해야 합니다. 변환 로직이 유효하지 않은 헤더나 쿼리 파라미터를 생성하면 해당 정책은 무시됩니다.