API Overview

DADP API 문서는 관리 API와 실행 API를 구분해 제공한다. 관리 API는 정책, 키 메타데이터, 연동 등록 같은 제어 정보를 다루고, 실행 API는 실제 암복호화 요청을 처리한다.

공개 API 표면

서비스	API 경계	대표 경로	주요 호출 주체
Hub	제어면 API	/api/v1, /api/v2	운영자 UI, 제어면 연동 클라이언트
Engine	실행 API	/api/*	Direct API, Wrapper, DB UDF
Engine	운영 API	/engine/api/v1/*	Hub, 운영 자동화

API 경계 규칙

1. Hub API는 정책, 키 메타데이터, 연동 등록, 운영 상태 같은 제어면 원본을 다룬다.
2. Engine API는 애플리케이션과 연동 도구가 사용할 수 있는 암복호화 실행 계약을 다룬다.
3. Engine Operations API는 Engine 등록, 상태 점검, 캐시 동기화 같은 운영 자동화 경로를 다룬다.
4. Hub에서 쓰는 식별자 계약과 Engine 실행 요청 본문은 동일한 모델이 아니다.
5. Direct API, Wrapper, DB UDF는 모두 최종적으로 Engine 실행 API를 사용한다.

운영자가 구분해야 할 것

Hub API

• 원본 상태를 생성, 변경, 조회한다.
• 운영자 인증과 권한 모델의 영향을 직접 받는다.
• 정책 변경 미반영, 인스턴스 등록 오류, 운영 설정 문제를 진단할 때 먼저 본다.

Engine API

• 실제 암복호화 요청을 처리한다.
• 실행 지연, 실패, 캐시 불일치, 실행 오류를 진단할 때 먼저 본다.
• 프로세스 생존 여부만이 아니라 실제 실행 요청과 응답 계약을 함께 봐야 한다.

Engine Operations API

• Hub가 Engine runtime을 관리하기 위해 사용한다.
• 일반 애플리케이션, Direct API 클라이언트, Wrapper 연동 코드, DB UDF 호출자가 직접 사용하는 API가 아니다.
• runtime identity, heartbeat, cache sync, stats 연결 점검 문제를 진단할 때 본다.

계약 해석 원칙

• 제어면 성공이 곧 실행면 성공을 의미하지는 않는다.
• 실행면 정상도 제어면 원본이 최신 상태라는 뜻은 아니다.
• 운영 API가 정상이어도 외부 연동 실행 API의 성공을 별도로 검증해야 한다.
• 같은 HTTP 오류라도 어느 경계에서 발생했는지에 따라 운영 해석이 달라진다.
• 연동 경로 문서는 API 문서를 대체하지 않는다. 연동 문서는 호출 위치를 설명하고, API 문서는 계약 자체를 설명한다.

읽는 순서

1. Hub API에서 제어면 경계와 원본 데이터를 먼저 이해한다.
2. Engine API에서 외부 연동 실행 계약을 확인한다.
3. Engine Operations API에서 Hub-Engine 운영 경계를 확인한다.
4. Wrapper Integration과 DB UDF Integration으로 실제 호출 경계 차이를 본다.