본문으로 건너뛰기
hits

[BE] 외부 API 연동은 전달이 아니라 번역이다

, 약 7분
HyoYoonNam
Software Engineer
이 글을 읽으면
  • 외부 API 연동을 단순한 DTO 매핑이 아니라 서로 다른 계약을 번역하는 과정으로 바라볼 수 있어요.
  • 외부 데이터의 번역 경계를 어디에 두고, 언제 더 바깥으로 옮겨야 하는지 알 수 있어요.

1. DTO를 분리하면 외부 API로부터 독립적일까?​

Chaekchaek은 도서 검색을 위해 알라딘 Search API를 사용한다.

알라딘에서 받은 응답을 그대로 클라이언트에 반환하지는 않았다. 외부 API 응답을 받는 DTO와 클라이언트에 반환할 DTO를 처음부터 따로 만들었다.

Aladin Search API
↓ (백엔드 경계 시작)
AladinSearchResponse
↓
BookSearchResponse
↓ (백엔드 경계 종료)
Chaekchaek Client

겉으로 보면 외부 API와 공개 API는 이미 분리되어 있다.

하지만 실제 BookSearchResponse에는 알라딘 API의 표현 방식인 totalResults, startIndex, itemsPerPage 등이 여전히 남아 있다.

public record BookSearchResponse(
int totalResults,
int startIndex,
int itemsPerPage,
boolean hasNext,
List<BookItem> items
) {
}

객체는 둘로 나뉘었지만, 외부 API가 데이터를 표현하는 방식은 공개 계약에 그대로 남아 있었다.

클라이언트가 의존해야 하는 대상은 알라딘의 계약이 아니라 Chaekchaek이 정의한 계약이다.

DTO를 분리하는 일과 외부 계약으로부터 독립하는 일은 같지 않았다.


2. 외부 API와 우리 서비스는 서로 다른 언어를 쓴다​

같은 책 검색 API라도 공급자마다 데이터를 표현하는 방식은 다를 수 있다.

의미알라딘다른 공급자
검색 결과itemdocuments
저자역할까지 포함한 author: Stringauthors: String[]
번역자author 안에 포함translators: String[]
다음 페이지페이지 관련 값을 이용해 계산is_end 등 별도 상태 제공

필드 이름만 다른 것도 아니다.

같은 정보를 어떤 단위로 나누고 어떤 상태로 표현할지 자체가 다르다.

두 표현 중 어느 하나가 절대적으로 더 올바른 것은 아니다.

알라딘에는 알라딘의 모델이 있고, Chaekchaek에는 Chaekchaek의 모델이 있다.

외부 API 연동은 단순히 필드명을 바꾸는 작업이 아니다. 외부 시스템의 정보를 우리 서비스에서 유의미한 정보로 번역하는 작업이다.

실제로 했던 번역은 다음 세 가지다.

  1. 외부의 용어를 우리 서비스의 용어로 바꾸는 것
    • ex. 검색된 책의 개수에 대한 용어를 totalResults -> totalCount
  2. 외부의 비정형 표현을 우리 서비스가 사용할 구조로 바꾸는 것
    • ex. 저자와 식자 표현을 모두 하나의 문자열 -> 저자, 식자 각각 문자열 배열
  3. 외부 시스템의 상태 정보를 클라이언트가 취할 다음 행동으로 바꾸는 것
    • ex. 페이지네이션을 현재 페이지 번호 -> 다음 페이지 번호

특히 뒤의 두 작업에는 단순 매핑을 넘어 우리 서비스가 무엇을 의미 있는 정보로 볼 것인지에 대한 정책이 담긴다.


3. 외부 DTO는 외부의 언어를 보존한다​

이런 의문이 생길 수 있다.

어차피 우리 서비스가 author와 translator를 구분해서 사용할 거라면, 알라딘으로부터 응답을 받는 순간부터 나누면 되는 거 아니야?
굳이 AladinSearchResponse와 BookSearchResponse를 나눌 필요가 있을까?

물론 기술적으로는 가능하다. 그래도 알라딘 응답용 DTO는 유지하는 편이 좋다.

SOLID 원칙은 이미 익숙하다고 가정하겠다. 그중에서도 SRP는 외부 응답을 받는 DTO가 별도로 필요한 이유를 잘 설명한다.

책 검색 API에 쓰이는 두 DTO는 서로 다른 이유로 변경된다.

AladinSearchResponse의 변경 이유
→ 알라딘 API의 계약이 바뀌었을 때

Chaekchaek의 검색 결과 모델의 변경 이유
→ Chaekchaek의 요구사항이 바뀌었을 때

두 DTO는 서로 다른 책임을 가진다.

두 DTO를 분리해야 외부 API의 변화가 우리 서비스의 계약으로 그대로 전파되는 일을 막을 수 있다.


4. 번역은 이름을 바꾸는 것보다 많은 일을 한다​

실제 구현에서 특히 필요했던 번역은 두 가지였다.

4.1. 기여자 표현을 구조로 번역한다​

알라딘은 저자와 번역자를 다음처럼 하나의 문자열에 담는다.

앤디 위어 (지은이), 박아람 (옮긴이)

하지만 우리 클라이언트는 저자와 번역자를 구분해 사용해야 했다.

{
"authors": ["앤디 위어"],
"translators": ["박아람"]
}

그래서 문자열을 해석하는 AladinContributorParser를 만들었다.

이 과정에서 쉼표만 기준으로 나눌 수는 없다는 사실도 알게 됐다.

민관식 (필명, 청원) (지은이)

괄호 안의 쉼표는 사람을 구분하는 기호가 아니다.

알라딘이 제공하는 문자열의 규칙을 해석하고, 이를 Chaekchaek이 이해할 수 있는 구조로 변환해야 했다.

중요한 것은 파싱 알고리즘 자체가 아니다.

외부의 표현을 그대로 전달하지 않고 우리 서비스에 필요한 의미로 바꾸었다는 데 있다.

이때부터 무엇을 보존하고 무엇을 버릴지도 결정하게 된다.

예를 들어 현재 서비스에서 지은이, 옮긴이만 사용하고 그림, 감수, 엮은이를 제외한다면, 그것 역시 하나의 결정이다.

번역 과정에서 발생하는 정보 손실도 하나의 정책이다.

4.2. 페이지 상태를 다음 행동으로 번역한다​

알라딘은 다음 세 값으로 페이지 정보를 표현한다.

totalResults
startIndex
itemsPerPage

처음에는 이 값들과 hasNext를 공개 API에도 제공했다.

그러면 클라이언트는 다음 페이지를 요청하기 위해 이런 규칙을 알아야 한다.

const nextPage = hasNext ? startIndex + 1 : null;

하지만 이 계산 규칙은 알라딘의 페이지 모델을 아는 서버가 처리할 수 있고, 처리하는 편이 낫다.

그래서 공개 응답은 다음처럼 단순해졌다.

public record BookSearchResponse(
int totalCount,
Integer nextPage,
List<BookItem> items
) {
}

이제 클라이언트는 알라딘의 페이지네이션 방식을 몰라도 된다. nextPage가 있다면 그 값을 요청하면 된다.

nextPage = 3
→ 다음 요청에서 3을 사용한다.

nextPage = null
→ 더 이상 요청할 페이지가 없다.

여기서 hasNext와 nextPage는 비슷해 보이지만 의미가 다르다.

hasNext는 현재 상태를 알려준다.

반면 nextPage는 클라이언트가 다음에 해야 할 행동에 필요한 값을 알려준다.

클라이언트는 더 이상 startIndex, itemsPerPage의 의미나 다음 페이지를 계산하는 방법을 알 필요가 없다.

핵심은 필드를 줄인 데 있지 않다.

외부 시스템의 상태를 그대로 노출하는 대신, 우리 클라이언트가 취할 다음 행동으로 번역했다.


5. 번역의 경계는 어디에 둘까?​

당시 번역은 BookSearchService에서 이루어졌다.

Aladin Search API
↓
AladinBookClient
↓
AladinSearchResponse
↓
BookSearchService
- 기여자 구조화
- nextPage 계산
- 필드 변환
↓
BookSearchResponse
↓
Chaekchaek Client

이 구조 덕분에 클라이언트는 알라딘의 필드명이나 페이지 계산 규칙을 알 필요가 없었다.

다만 BookSearchService는 여전히 AladinSearchResponse, AladinBookItem처럼 외부 공급자의 타입을 직접 알고 있었다.

외부 계약은 공개 API까지 오지 않았지만, 애플리케이션 서비스까지는 들어와 있었다.

그렇다고 이 구조가 처음부터 잘못된 선택이었던 것은 아니다.

당시 검색 공급자는 하나였고 검색 기능을 빠르게 완성하는 일이 더 중요했다.

추상화 자체도 비용이기 때문이다.

중요한 것은 처음부터 모든 경계를 완벽하게 만드는 일이 아니라, 현재 경계가 어떤 변경 비용을 남기고 있는지 아는 것이다.

검색 공급자의 교체나 추가가 실제 변경 가능성으로 다가온다면, 번역이 애플리케이션 서비스에 도달하기 전에 끝나도록 경계를 옮길 수 있다.

Aladin Search API
↓
Aladin Adapter
- 외부 계약 해석
- 기여자 구조화
- 페이지 정보 계산
↓
BookSearchResult
↓
BookSearchService

서비스가 받는 시점에는 이미 Chaekchaek이 정의한 검색 결과가 된다.

이제 BookSearchService는 검색 결과가 어느 공급자에서 왔는지, 공급자가 데이터를 어떤 형식으로 표현하는지 알 필요가 없다.

중요한 것은 특정 인터페이스나 어댑터 패턴 자체가 아니다.

좋은 경계의 위치는 처음부터 고정되어 있는 것이 아니라, 변경 압력에 따라 달라질 수 있다.


6. 외부 응답이 바뀌면 번역도 틀릴 수 있다​

앞에서는 알라딘의 기여자 문자열을 AladinContributorParser가 해석하도록 만들었다.

앤디 위어 (지은이), 박아람 (옮긴이)

이 파서는 (지은이), (옮긴이)와 같은 알라딘의 표현 규칙을 알고 있다.

그런데 여기에는 한 가지 전제가 있다.

알라딘이 앞으로도 우리가 예상한 형식으로 값을 내려준다는 전제다.

만약 새로운 역할(ex. 엮은이)이 추가되거나, 기존과 다른 형식의 문자열(ex.지은이=앤디 위어, ...)이 내려온다면 어떻게 될까?

JSON 필드가 사라진 경우처럼 역직렬화 단계에서 바로 실패할 수도 있지만, 더 까다로운 경우는 코드는 정상적으로 실행되는데 결과만 잘못되는 경우다.

예를 들어 파서가 어떤 기여자를 저자로 잘못 분류하거나, 알 수 없는 역할을 그냥 버린다면 요청 자체는 성공한다. 문제는 잘못된 데이터가 정상적인 검색 결과처럼 클라이언트까지 전달될 수 있다는 것이다.

외부 응답의 변화를 어떻게 발견할지, 해석할 수 없는 값을 어떻게 처리할지, 어느 수준까지 방어할지는 별도의 주제로 더 다뤄볼 수 있다.


7. 외부 API 연동은 번역이다​

처음에는 외부 API 연동을 단순히 데이터를 받아 전달하는 일이라고 생각했다.

알라딘 응답
→ DTO에 담는다
→ 필요한 필드만 골라 반환한다

하지만 구현하면서 실제로 한 일은 달랐다.

알라딘이 하나의 문자열로 제공한 기여자 정보에서 저자와 번역자를 나눴다.

앤디 위어 (지은이), 박아람 (옮긴이)

↓

authors: ["앤디 위어"]
translators: ["박아람"]

알라딘이 제공한 페이지 정보도 그대로 노출하지 않고, 클라이언트가 바로 사용할 수 있는 nextPage로 바꿨다.

totalResults + startIndex + itemsPerPage

↓

nextPage

알라딘이 제공한 페이지 정보도 그대로 노출하지 않고, 클라이언트가 바로 사용할 수 있는 nextPage로 바꿨다.

알라딘의 페이지 정보
totalResults + startIndex + itemsPerPage

↓

클라이언트가 사용할 값
nextPage

이처럼 외부 API 연동에서는 단순히 값을 옮기는 것보다, 외부의 표현을 우리 서비스에 필요한 형태로 바꾸는 일이 더 중요했다.

이 글에서 말하는 번역은 바로 이 과정을 뜻한다.


리로그 원문