이 API는 누가 부르나요?
조회·수정 API를 만들고 나서 이런 생각이 들었습니다. 다른 도메인의 서버가 이 데이터를 쓸 수도 있으니 인터널 API도 지금 함께 뚫어두는 게 낫지 않을까. 알아보니 원칙은 간단했습니다. 필요할 때 만든다. 그 한 줄 안에 API를 종류로 나누는 기준과, 만들지 않는 것도 설계라는 감각이 함께 들어 있었습니다.
같은 데이터를 내주는 API인데 왜 종류가 나뉘고, 그 기준은 무엇일까요?
이 글에서 다루는 내용
지난 글 끝에서 예고한 대로, API를 퍼블릭·오퍼레이션·인터널로 나누는 기준과 호출자에 따라 인증·인가 책임이 달라지는 이유를 살펴봅니다.
호출자로 API 구분하기
이 글에서는 호출자에 따라 API를 세 종류로 구분합니다. 이는 해당 시스템의 관례이며 보편 표준은 아닙니다. 같은 데이터를 다루더라도 고객 클라이언트, 운영 도구, 다른 서비스가 필요한 기능과 권한은 다릅니다.
| 종류 | 호출자 | 권한의 기준 |
|---|---|---|
| 퍼블릭(public) | 실제 고객의 클라이언트 | 최종 사용자의 역할과 리소스 범위 |
| 오퍼레이션(operation) | 어드민·백오피스 | 운영자 권한 |
| 인터널(internal) | 다른 도메인의 서버 (서버-투-서버) | 호출하는 서비스의 신원과 범위 |
처음엔 "API면 다 같은 API지, 왜 굳이 종류를 나누나" 싶었습니다. 그런데 이 셋은 호출자가 다르기 때문에 계약의 성격이 다릅니다. 퍼블릭은 불특정 다수의 고객이 부르니 하위 호환에 민감하고, 권한을 최종 사용자 단위로 판단합니다. 오퍼레이션은 운영자용이라 강력한 기능이 열리되 운영자 권한으로 잠급니다. 인터널은 사람이 아니라 서비스가 호출자이므로, 호출하는 서비스가 누구인지를 확인합니다. 사용자를 대신한 호출이라면 사용자 권한도 함께 전달하고 검사할 수 있습니다. 하나의 컨트롤러에 뭉쳐두면 이 세 가지 성격이 한 코드에 섞이게 됩니다.
프론트엔드에서는 패키지의 public export와 내부 모듈을 나누는 방식이 비슷합니다. 누가 사용할 수 있는지를 주석이 아니라 모듈 경계로 강제한다는 점에서 같습니다.
인터널의 경계는 네트워크가 아니라 도메인입니다
셋 중에서 프론트엔드 개발자에게 가장 낯선 것이 인터널입니다. 처음엔 "내부망에서 부르는 API"라는 뜻인 줄 알았는데, 이 구조에서는 인터널 API를 다른 도메인의 서비스가 호출하는 계약으로 구분합니다. 일반적으로 internal API라는 말은 조직 내부용 API까지 넓게 쓰이므로, 도메인이 같아도 내부 API라고 부를 수 있습니다.
예를 들어 급여 도메인이 급여 명세를 만드는 상황을 생각해 보겠습니다. 급여 도메인이 가진 것은 구성원의 식별자뿐이고 이름과 소속 같은 구성원 정보는 프로필 도메인의 것입니다. 이때 클라이언트가 두 도메인을 각각 불러서 화면에서 합치는 게 아니라, 급여 서버가 프로필 도메인의 인터널 API를 불러 완성본을 만들어 내려줍니다. 서버가 서버를 부르는 것입니다.
여러 서비스의 데이터를 서버에서 조합한다는 점은 BFF(Backend for Frontend) 와 비슷합니다. 이 예제에서는 별도 BFF 대신 급여 서버가 프로필 서버를 호출해 필요한 정보를 모읍니다.
API 종류마다 인가 기준이 다릅니다
호출자가 달라지면 생성 시점과 쓰기 범위, 인증 기준도 달라집니다.
첫째, 모든 API가 인터널을 갖는 것은 아닙니다. 필요할 때 만듭니다. 요구가 없을 때 인터널 API를 미리 만들면 사용되지 않는 계약과 추가 인증·인가 경로를 유지해야 합니다. 소비자가 생긴 뒤 요구에 맞춰 만드는 편이 낫습니다.
둘째, "인터널은 읽기 전용" 같은 규칙을 미리 못 박기는 어렵습니다. 알림 생성처럼 인터널이 쓰기를 맡는 것이 자연스러운 경우가 있습니다. 다른 도메인의 서버가 "이 사용자에게 알림을 만들어 달라"고 부르는 식입니다. 상황마다 다른 것을 규칙으로 묶으면 규칙이 곧 기술 부채가 됩니다. 대신 쓰기를 여는 인터널은 그만큼 인가를 더 좁게 잡아야 합니다.
셋째, 사용자 권한 판단과 서비스 간 호출 검증을 나눕니다. 이 구조에서 퍼블릭 API는 최종 사용자의 역할과 접근 범위를 판단합니다. 인터널 API는 호출한 서비스의 신원과 허용된 작업을 확인하고, 해당 테넌트와 리소스에 접근할 수 있는지도 검사합니다.
내부망에서 온 요청이라는 이유만으로 이 검사를 생략할 수는 없습니다. 클러스터 안의 워크로드가 침해되거나 설정이 잘못 열리면 허용하지 않은 호출이 들어올 수 있습니다.
그래서 기준선은 이렇게 잡는 편이 낫습니다.
- 인터널도 호출자를 인증합니다. mTLS나 서비스 토큰처럼 "어느 서비스가 부르는가"를 증명하게 하고, 서비스마다 부를 수 있는 인터널의 목록을 좁힙니다.
- 테넌트와 리소스 범위는 인터널에서도 다시 검사합니다. 사용자 역할은 퍼블릭이 판단하더라도, "이 테넌트의 데이터를 이 호출이 만질 수 있는가"는 데이터를 가진 쪽이 답해야 합니다.
- "안에서는 신뢰"를 인가 생략으로 읽지 않습니다. 경계 하나가 뚫렸을 때 막을 것이 남아 있어야 합니다. 이것이 제로 트러스트가 말하는 바이고, 급여나 인사처럼 민감한 데이터를 다루는 도메인에서는 특히 그렇습니다.
다음 글에서는 API 응답을 도메인 모델과 얼마나 결합할지 살펴봅니다.
FE ↔ BE 대응표
이 글에서 다룬 대응입니다.
| BE 개념 | FE에서 가장 가까운 것 | 대응의 핵심 |
|---|---|---|
| 퍼블릭 / 인터널 분리 | public export vs 내부 모듈 | 호출자에 따라 계약의 엄격함이 다르다 |
| 인터널 API | BFF의 서버 간 조립 | 클라이언트 대신 서버가 합친다 |
| 사용자 권한의 자리 | 라우트 가드 | 관문에서 사람을 확인한다 |
| 서비스 간 인증 | (대응물 없음) | 안쪽에서는 서비스를 확인한다 |
References
API 경계와 조립
만들지 않는 설계
서비스 간 인증과 신뢰 경계
