구절 API에 식별자 추가로 음성 변환 연동 가능해졌다
목차
구절 응답 API에 pickId를 추가했다. 간단해 보이지만, 이 한 줄의 변경이 없으면 앱 서버에서 음성 변환 요청을 제대로 날릴 수 없었다.
왜 ID가 필요했나
처음엔 구절 정보(제목, 본문, 참고 등)만 응답으로 돌려줬다. 앱 입장에선 사용자에게 보여줄 데이터가 다 있으니 충분했다. 그런데 TTS(음성 변환) 기능이 추가되면서 상황이 달라졌다.
앱 서버에서 TTS 엔진을 호출할 때, "이 구절을 읽어 달라"고 요청하려면 어떤 구절인지 명확히 식별할 수 있는 값이 필요했다. 사용자가 요청한 구절의 제목이나 본문 텍스트만으로는 시스템상 고유한 레코드를 찾기 어렵다. 특히 같은 본문이 여러 구절에 들어있다면 더욱 그렇다.
그래서 필요한 게 verse.id — 데이터베이스에서 각 구절을 유일하게 식별하는 키값이다. 이걸 응답에 담아야 앱이 음성 요청을 할 때 "ID 12345 구절을 TTS 처리해 달라"고 정확히 전달할 수 있다.
작은 누락, 큰 영향
이런 상황은 꽤 자주 마주친다. 초기 API 설계 시에는 현재 필요한 필드만 응답으로 만든다. 나중에 새로운 기능(음성, 공유, 분석 등)이 추가되면서 "아, 이 정보가 필요했네" 하고 발견한다.
이번 경우 두 가지 선택지가 있었다:
1. 구절 API는 그대로 두고, 음성 기능에서는 별도로 ID를 조회하는 로직 추가
2. 구절 API 응답 자체에 ID를 포함시키기
첫 번째 방법은 불필요한 네트워크 호출을 추가하고, 코드가 복잡해진다. 두 번째가 간단하고 명확하다. 그래서 응답 DTO에 pickId를 추가했다.
API 응답 before: { title, content, reference, ... }
API 응답 after: { pickId, title, content, reference, ... }
배운 점: 인터페이스 설계는 미래를 본다
이 일을 겪으면서 느낀 건, 초기 API 설계 때 "이걸 누가 어떻게 쓸까"를 조금 더 깊이 생각해야 한다는 것이다.
특히 마이크로서비스 구조에서 한 서버의 응답이 다른 여러 서버의 입력이 된다면, 단순히 "화면에 필요한 필드"만 골라서 내보내면 안 된다. 음성, 공유, 검색 인덱싱, 분석 등 예상 가능한 downstream 기능들을 고려해서 응답에 포함할 기본 정보를 정하는 게 좋다.
물론 과하게 모든 필드를 다 담을 순 없다 (성능, 보안). 하지만 ID나 타임스탬프처럼 메타데이터성 필드는 거의 비용 없이 추가할 수 있으니, 미리 포함시키는 게 현명하다.
다음 번엔 새 API를 설계할 때, 요구사항서만 읽지 말고 팀에 물어봐야겠다. "이 데이터를 앱에서, 분석 서버에서, 어떻게 쓸 예정이야?" 하면 필요한 필드들이 더 명확해진다.
🛒 이 글과 어울리는 추천 상품
*위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.
댓글 0
첫 댓글 달아줘.