Engine API¶

Engine API는 애플리케이션과 연동 도구가 DADP 암복호화 기능을 호출할 때 사용하는 실행 API다.

이 문서는 단건, 배치, 스트림 암복호화 요청에 필요한 경로, 요청 본문, 응답 본문, 오류 해석 기준을 정리한다.

API Scope¶

구분	대표 경로	호출 주체	목적
상태 API	`/health`, `/actuator/health`, `/api/health`	운영자, 배포 자동화	프로세스와 서비스 가용성 점검
실행 API	`/api/*`	Direct API, Wrapper, DB UDF	단건, 배치, 스트림 암복호화

Context path

배포 구성에 따라 /engine context path가 붙은 경로를 함께 사용할 수 있다. 공개 연동 문서에서는 실행 API의 표준 경로를 /api/* 기준으로 표기한다.

Base URL¶

Engine API의 전체 URL은 배포 환경의 Engine endpoint와 API path를 조합해 만든다.

배포 형태	Base URL 예시	단건 암호화 Full URL 예시
로컬 검증	`http://localhost:8080`	`http://localhost:8080/api/encrypt`
내부망 배포	`http://dadp-engine.internal:8080`	`http://dadp-engine.internal:8080/api/encrypt`
TLS reverse proxy	`https://engine.example.com`	`https://engine.example.com/api/encrypt`
context path 사용	`https://engine.example.com/engine`	`https://engine.example.com/engine/api/encrypt`

이 문서의 예시는 다음 값을 기준으로 작성한다.

ENGINE_BASE_URL=http://localhost:8080

운영 환경에서는 ENGINE_BASE_URL을 실제 Engine endpoint로 바꿔 사용한다.

대표 실행 경로¶

경로	메서드	역할
`/health`	`GET`	서비스 health
`/actuator/health`	`GET`	Spring 호환 health
`/api/health`	`GET`	런타임 가용성 점검
`/api/encrypt`	`POST`	단건 암호화
`/api/decrypt`	`POST`	단건 복호화
`/api/encrypt/batch`	`POST`	배치 암호화
`/api/decrypt/batch`	`POST`	배치 복호화
`/api/encrypt/stream`	`POST`	스트림 암호화
`/api/decrypt/stream`	`POST`	스트림 복호화

Health 호출 예시¶

curl -fL "${ENGINE_BASE_URL}/api/health"

Full URL 예시:

curl -fL "http://localhost:8080/api/health"

Health 응답¶

{
  "status": "UP",
  "service": "dadp-engine",
  "version": "6.0.0"
}

version은 Engine 실행 바이너리 기준 버전이다. 외부 제출 제품명과 동일한 의미로 해석하지 않는다.

단건 호출 계약¶

단건 암호화 요청¶

POST /api/encrypt

요청 본문:

필드	필수	설명
`data`	예	암호화할 평문
`policyCode`	조건부	고정 정책 코드. `policyName`과 함께 사용할 수 없다.
`policyName`	조건부	최신 정책명 기준 암호화. `policyCode`가 없을 때 사용한다.
`policyVersion`	아니오	`policyName`과 함께 사용하는 양수 버전

policyCode 또는 policyName 중 하나는 반드시 필요하다.

{
  "data": "DADP_TEST",
  "policyName": "sample"
}

호출 예시:

curl -fL -X POST "${ENGINE_BASE_URL}/api/encrypt" \
  -H "Content-Type: application/json" \
  -d '{
    "data": "DADP_TEST",
    "policyName": "sample"
  }'

Full URL 예시:

curl -fL -X POST "http://localhost:8080/api/encrypt" \
  -H "Content-Type: application/json" \
  -d '{
    "data": "DADP_TEST",
    "policyName": "sample"
  }'

응답 본문:

{
  "success": true,
  "data": "hub:ABCD2345:...",
  "policyCode": "ABCD2345"
}

단건 복호화 요청¶

POST /api/decrypt

단건 복호화 요청 본문은 data 필드에 ciphertext를 넣는다. encryptedData, policyCode, policyName, policyVersion은 단건 복호화 요청에 넣지 않는다. Engine은 ciphertext에서 policy code를 추출해 실행키를 해석한다.

{
  "data": "<encrypted-data>"
}

호출 예시:

curl -fL -X POST "${ENGINE_BASE_URL}/api/decrypt" \
  -H "Content-Type: application/json" \
  -d '{
    "data": "hub:ABCD2345:..."
  }'

Full URL 예시:

curl -fL -X POST "http://localhost:8080/api/decrypt" \
  -H "Content-Type: application/json" \
  -d '{
    "data": "hub:ABCD2345:..."
  }'

응답 본문:

{
  "success": true,
  "data": "DADP_TEST",
  "policyCode": "ABCD2345"
}

배치 호출 계약¶

배치 요청¶

POST /api/encrypt/batch 또는 POST /api/decrypt/batch

요청 본문:

{
  "items": [
    {
      "data": "alpha",
      "policyName": "sample"
    },
    {
      "data": "beta",
      "policyName": "sample"
    }
  ]
}

Engine은 하위 호환을 위해 requests 배열도 수용한다. 공개 연동에서는 items를 표준으로 사용한다.

배치 암호화 호출 예시:

curl -fL -X POST "${ENGINE_BASE_URL}/api/encrypt/batch" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "data": "alpha",
        "policyName": "sample"
      },
      {
        "data": "beta",
        "policyName": "sample"
      }
    ]
  }'

Full URL 예시:

curl -fL -X POST "http://localhost:8080/api/encrypt/batch" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "data": "alpha",
        "policyName": "sample"
      },
      {
        "data": "beta",
        "policyName": "sample"
      }
    ]
  }'

배치 암호화 응답¶

{
  "success": true,
  "transportMode": "json",
  "results": [
    {
      "success": true,
      "code": 1000,
      "message": "encrypt succeeded",
      "originalData": "alpha",
      "encryptedData": "hub:ABCD2345:...",
      "policyCode": "ABCD2345"
    }
  ],
  "totalProcessed": 1,
  "totalSuccess": 1,
  "totalFailed": 0,
  "totalProcessingTime": 12
}

배치 복호화 응답¶

{
  "success": true,
  "transportMode": "json",
  "results": [
    {
      "success": true,
      "code": 1000,
      "message": "decrypt succeeded",
      "originalData": "hub:ABCD2345:...",
      "decryptedData": "alpha",
      "policyCode": "ABCD2345"
    }
  ],
  "totalProcessed": 1,
  "totalSuccess": 1,
  "totalFailed": 0,
  "totalProcessingTime": 9
}

실패한 항목은 success=false, code=2000, message=<error>를 반환한다. 배치 전체 HTTP status는 요청을 정상 처리한 경우 200 OK이며, 개별 실패는 results[]에서 확인한다.

스트림 호출 계약¶

POST /api/encrypt/stream 또는 POST /api/decrypt/stream

요청은 NDJSON이다. 각 줄은 단건 요청 본문과 같은 JSON 객체다.

{"data":"alpha","policyName":"sample"}
{"data":"beta","policyName":"sample"}

스트림 암호화 호출 예시:

printf '%s\n' \
  '{"data":"alpha","policyName":"sample"}' \
  '{"data":"beta","policyName":"sample"}' \
  | curl -fL -X POST "${ENGINE_BASE_URL}/api/encrypt/stream" \
      -H "Content-Type: application/x-ndjson" \
      --data-binary @-

Full URL 예시:

printf '%s\n' \
  '{"data":"alpha","policyName":"sample"}' \
  '{"data":"beta","policyName":"sample"}' \
  | curl -fL -X POST "http://localhost:8080/api/encrypt/stream" \
      -H "Content-Type: application/x-ndjson" \
      --data-binary @-

응답도 NDJSON이다. 각 줄은 단건 응답 본문과 같은 JSON 객체다.

{"success":true,"data":"hub:ABCD2345:...","policyCode":"ABCD2345"}
{"success":true,"data":"hub:ABCD2345:...","policyCode":"ABCD2345"}

배치 및 전송 형식¶

모드	Content-Type	설명
단건 JSON	`application/json`	단건 암복호화
배치 JSON	`application/json`	`items[]` 기반 배치 처리
스트림	`application/x-ndjson`	연속 스트림 처리
바이너리 프레임	`application/x-dadp-binary-frame`	배치 전송의 binary frame 형식

application/x-dadp-binary-frame은 배치 endpoint에서 처리한다. 단건 바이너리 프레임을 공개 계약으로 전제하지 않는다.

오류 응답¶

상황	HTTP status	응답 예
지원하지 않는 메서드	`405`	`{"error":"method not allowed"}`
요청 JSON decode 실패	`400`	`{"error":"decode request: ..."}`
암호화 요청에 정책 식별자 없음	`400`	`{"success":false,"error":"encrypt request requires policyCode or policyName"}`
복호화 요청에 정책 필드 포함	`400`	`{"success":false,"error":"decrypt request accepts data only"}`
Engine crypto service 미설정	`503`	`{"error":"crypto service is not configured"}`

운영 해석¶

Engine은 정책 원본을 소유하지 않는다.
Engine은 Hub에서 배포된 런타임 캐시를 기준으로 실행한다.
단순 health 성공은 정책/키 캐시가 최신이라는 뜻이 아니다.
실행 실패와 캐시 미동기화는 구분해서 진단해야 한다.
Engine 운영 API는 일반 애플리케이션 연동 경로가 아니다. 운영 진단과 자동화가 필요한 경우 Engine Operations API를 확인한다.