겹칠 수 있는 API 요청의 범위를 정하는 법

API 요청을 검토할 때 어려운 점은 구현 자체보다 범위를 어디까지 잡느냐에 있다. 이번 요청도 표면만 보면 한 업무 기능을 지원하는 2차 API를 만드는 일이었다. 그러나 비슷한 시기에 다른 관계 조직도 더 넓은 용도의 Open API를 준비하고 있었다. 두 작업이 같은 영역을 다루는지 확인하지 않고 시작하면 중복 개발이 생길 수 있었다.

그렇다고 예정된 API의 전체 범위가 정리될 때까지 현재 요청을 멈추는 것도 적절하지 않았다. 당장 필요한 기능은 분명했고, 앞으로 상태 변경이나 보류 처리, 첨부서류, 메모와 댓글까지 요구가 늘어날 가능성도 이미 제기된 상태였다. 지금 필요한 범위와 이후 확장될 범위를 한 덩어리로 다루지 않는 판단이 필요했다.

문제를 다시 정의하기

처음에는 현재 요청이 다른 조직의 작업과 겹치는지를 확인하는 문제처럼 보였다. 실제로는 중복 여부만 가리는 일이 아니었다. 현재 필요한 기능의 착수를 늦추지 않으면서 예정된 Open API와의 경계를 어디에서 확인할지 정해야 했다.

미래 요구를 모두 첫 범위에 넣으면 아직 확정되지 않은 기능까지 설계해야 한다. 반대로 현재 요청만 좁게 보면 상태 변경, 보류, 첨부서류, 메모와 댓글이 추가될 때 API의 범위를 다시 조정해야 할 수 있다. 핵심은 모든 요구를 미리 해결하는 데 있지 않았다. 지금 결정할 내용과 추가 확인이 필요한 내용을 분리하는 일이었다.

선택지를 나눈 기준

선택지는 현재 요청을 멈추고 전체 Open API의 범위를 먼저 맞추는 방법과, 요청받은 범위부터 그대로 착수하는 방법으로 나뉘었다. 판단 기준은 현재 요구가 충분히 구체적인지, 다른 작업과 실제로 겹치는 부분이 어디인지, 향후 기능이 어느 정도까지 늘어날 수 있는지였다.

검토 결과 현재 요청은 그대로 시작할 수 있었다. 다만 예정된 Open API와 중복될 가능성이 있는 부분까지 같다고 단정할 근거는 부족했다. 그래서 착수 여부와 중복 범위 확인을 하나의 결정으로 묶지 않았다. 전자는 진행하고 후자는 별도로 확인하기로 했다.

내린 결정과 실행

현재 요청은 예정대로 착수하되 다른 조직이 준비하는 API와 겹치는 영역은 따로 점검하기로 했다. 아직 정해지지 않은 세부 범위를 임의로 넓히지도 않았다. 구체적인 기능 경계는 백엔드 담당자와 기획 논의에서 확정하기로 정했다.

확장 가능성은 초기 범위에 모두 넣는 대신 이후 논의에서 빠지지 않도록 판단 조건으로 남겼다. 상태 변경과 보류 처리뿐 아니라 첨부서류, 메모, 댓글처럼 성격이 다른 기능까지 늘어날 수 있다는 요구를 함께 고려해야 했다.

결과와 남은 문제

현재 요청을 중단하지 않고 시작한다는 방향은 정해졌다. 동시에 예정된 Open API와의 중복 가능성을 별도 확인 대상으로 분리했다. 범위가 확정되지 않았다는 이유로 전체 작업을 보류하거나, 반대로 확인 없이 넓은 API를 먼저 만드는 상황은 피했다.

아직 남은 일도 분명하다. 두 API가 실제로 어디에서 겹치는지 확인해야 하며, 확장 기능을 현재 구조가 어디까지 받아들일지도 담당자들과 정해야 한다. 이번에 확정한 것은 완성된 API 설계가 아니라 다음 판단을 위한 경계였다.

다음에 적용할 원칙

비슷한 요청을 받으면 착수 여부와 최종 범위 확정을 분리해 판단하려 한다. 현재 요구가 명확하다면 필요한 작업은 진행하되, 다른 조직의 계획과 겹칠 수 있는 부분은 별도의 확인 항목으로 남긴다.

확장 가능성도 초기 개발 범위를 무조건 키우는 근거로 쓰지 않는다. 대신 어떤 기능이 추가될 수 있는지 드러내고, 그 기능들이 현재 API와 같은 책임에 속하는지는 담당자들과 확인한다. 범위를 잘 정한다는 것은 처음부터 모든 답을 내놓는 일이 아니라, 지금 결정해도 되는 것과 아직 합의가 필요한 것을 구분하는 일에 가깝다.