제5장: 2단계 API 인터페이스

5.1 Phase 2 개요

Phase 2는 표준화된 데이터 형식(Phase 1)을 프로그래밍 방식으로 처리할 수 있는 API 인터페이스를 제공합니다. REST 및 GraphQL 엔드포인트를 통해 삭제 요청의 제출, 추적, 관리를 자동화합니다.

API 아키텍처

WIA-LEG-009 API는 RESTful 원칙을 따르며, 선택적으로 GraphQL도 지원합니다:

• Base URL: https://api.example.com/wia/rtbf/v1
• 인증: OAuth 2.0, API Key, JWT
• 형식: JSON (Content-Type: application/json)
• 버전 관리: URL 경로에 버전 포함 (/v1, /v2 등)

5.2 인증 및 권한

API Key 인증

가장 간단한 인증 방식. 요청 헤더에 API 키를 포함:

GET /wia/rtbf/v1/requests
Authorization: Bearer wia_api_key_abc123def456
Content-Type: application/json

OAuth 2.0 인증

더 안전한 인증 방식. Client Credentials Flow 권장:

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=your_client_id
&client_secret=your_client_secret
&scope=rtbf:read rtbf:write

Response:
{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "rtbf:read rtbf:write"
}

권한 스코프

5.3 핵심 REST 엔드포인트

{
  "wia_standard": "WIA-LEG-009",
  "version": "1.0",
  "request_type": "deletion",
  "data_subject": {
    "email": "user@example.com",
    "identifiers": [
      {"type": "user_id", "value": "12345"}
    ]
  },
  "legal_basis": "GDPR_Article_17_1a",
  "scope": {
    "data_categories": ["personal_data"],
    "include_backups": true
  },
  "callback_url": "https://your-app.com/rtbf/callback"
}

202 Accepted

{
  "request_id": "rtbf_20250101_abc123",
  "status": "pending_verification",
  "created_at": "2025-01-01T10:30:00Z",
  "estimated_completion": "2025-01-30T23:59:59Z",
  "verification": {
    "method": "email_otp",
    "expires_at": "2025-01-01T11:00:00Z"
  },
  "links": {
    "self": "/wia/rtbf/v1/requests/rtbf_20250101_abc123",
    "verify": "/wia/rtbf/v1/requests/rtbf_20250101_abc123/verify"
  }
}

200 OK

{
  "request_id": "rtbf_20250101_abc123",
  "status": "processing",
  "created_at": "2025-01-01T10:30:00Z",
  "verified_at": "2025-01-01T10:35:00Z",
  "progress": {
    "total_systems": 5,
    "completed_systems": 2,
    "percentage": 40
  },
  "timeline": [
    {
      "event": "request_created",
      "timestamp": "2025-01-01T10:30:00Z"
    },
    {
      "event": "identity_verified",
      "timestamp": "2025-01-01T10:35:00Z"
    },
    {
      "event": "deletion_started",
      "timestamp": "2025-01-01T11:00:00Z",
      "system": "customer_database"
    }
  ]
}

{
  "verification_code": "123456",
  "method": "email_otp"
}

200 OK

{
  "verified": true,
  "message": "Identity verified successfully",
  "next_status": "processing"
}

200 OK

{
  "requests": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "total_pages": 8
  }
}

200 OK

{
  "message": "Request cancelled successfully",
  "request_id": "rtbf_20250101_abc123",
  "status": "cancelled"
}

200 OK
Content-Type: application/pdf

[PDF 바이너리 데이터]

5.4 요청 상태 머신

요청은 다음 상태를 거쳐 진행됩니다:

┌────────────────┐
│  created       │ ← 요청 생성
└────────┬───────┘
         │
         ▼
┌────────────────┐
│ pending_       │ ← 신원 확인 대기
│ verification   │
└────────┬───────┘
         │
         ▼
┌────────────────┐
│ verified       │ ← 신원 확인 완료
└────────┬───────┘
         │
         ▼
┌────────────────┐
│ legal_review   │ ← 법적 검토 (예외 사항 확인)
└────────┬───────┘
         │
         ├──────────────────┐
         │                  │
         ▼                  ▼
┌────────────────┐   ┌──────────────┐
│ processing     │   │ rejected     │ ← 법적 사유로 거부
└────────┬───────┘   └──────────────┘
         │
         ▼
┌────────────────┐
│ completed      │ ← 삭제 완료
└────────────────┘

         또는

┌────────────────┐
│ failed         │ ← 기술적 오류로 실패
└────────────────┘

         또는

┌────────────────┐
│ cancelled      │ ← 사용자가 취소
└────────────────┘

상태 설명

5.5 Webhook 콜백

비동기 처리를 위해 요청 생성 시 callback_url을 제공하면, 상태 변경 시 자동으로 알림을 받을 수 있습니다.

콜백 페이로드

POST https://your-app.com/rtbf/callback
Content-Type: application/json
X-WIA-Signature: sha256=abc123... (HMAC 서명)

{
  "event": "request.completed",
  "timestamp": "2025-01-30T15:30:00Z",
  "data": {
    "request_id": "rtbf_20250101_abc123",
    "status": "completed",
    "completion_details": {
      "systems_processed": 5,
      "records_deleted": 1523,
      "backups_cleaned": 3
    }
  }
}

콜백 이벤트

• request.created: 요청 생성됨
• request.verified: 신원 확인됨
• request.processing: 처리 시작됨
• request.completed: 삭제 완료됨
• request.failed: 실패함
• request.rejected: 거부됨

서명 검증 (보안)

import crypto from 'crypto';

function verifyWebhookSignature(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const digest = 'sha256=' + hmac.update(payload).digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(digest)
  );
}

5.6 GraphQL API (선택 사항)

REST API 외에도 더 유연한 쿼리를 위해 GraphQL을 지원할 수 있습니다.

GraphQL 스키마

type Query {
  rtbfRequest(id: ID!): RTBFRequest
  rtbfRequests(
    page: Int = 1
    limit: Int = 20
    status: RTBFStatus
    email: String
  ): RTBFRequestConnection
}

type Mutation {
  createRTBFRequest(input: CreateRTBFRequestInput!): RTBFRequest
  verifyRTBFRequest(id: ID!, code: String!): RTBFRequest
  cancelRTBFRequest(id: ID!): RTBFRequest
}

type RTBFRequest {
  id: ID!
  status: RTBFStatus!
  createdAt: DateTime!
  dataSubject: DataSubject!
  progress: Progress
  timeline: [TimelineEvent!]!
}

enum RTBFStatus {
  CREATED
  PENDING_VERIFICATION
  VERIFIED
  LEGAL_REVIEW
  PROCESSING
  COMPLETED
  REJECTED
  FAILED
  CANCELLED
}

쿼리 예시

query GetRequestDetails {
  rtbfRequest(id: "rtbf_20250101_abc123") {
    id
    status
    createdAt
    dataSubject {
      email
    }
    progress {
      totalSystems
      completedSystems
      percentage
    }
    timeline {
      event
      timestamp
      system
    }
  }
}

뮤테이션 예시

mutation CreateRequest {
  createRTBFRequest(input: {
    requestType: DELETION
    dataSubject: {
      email: "user@example.com"
      identifiers: [
        {type: "user_id", value: "12345"}
      ]
    }
    legalBasis: "GDPR_Article_17_1a"
    scope: {
      dataCategories: ["personal_data"]
      includeBackups: true
    }
  }) {
    id
    status
  }
}

5.7 에러 처리

표준 에러 응답

400 Bad Request

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "The request is missing required fields",
    "details": [
      {
        "field": "data_subject.email",
        "issue": "Required field is missing"
      }
    ],
    "documentation_url": "https://docs.wia.org/rtbf/errors#INVALID_REQUEST"
  }
}

에러 코드

5.8 SDK 및 클라이언트 라이브러리

TypeScript/JavaScript SDK

import { WIARTBFClient } from '@wia/rtbf-sdk';

const client = new WIARTBFClient({
  apiKey: 'wia_api_key_abc123',
  baseUrl: 'https://api.example.com/wia/rtbf/v1'
});

// 요청 생성
const request = await client.createRequest({
  requestType: 'deletion',
  dataSubject: {
    email: 'user@example.com',
    identifiers: [{ type: 'user_id', value: '12345' }]
  },
  legalBasis: 'GDPR_Article_17_1a',
  scope: {
    dataCategories: ['personal_data'],
    includeBackups: true
  }
});

console.log(`Request created: ${request.id}`);

// 상태 확인
const status = await client.getRequest(request.id);
console.log(`Status: ${status.status}`);

Python SDK

from wia_rtbf import RTBFClient

client = RTBFClient(
    api_key='wia_api_key_abc123',
    base_url='https://api.example.com/wia/rtbf/v1'
)

# 요청 생성
request = client.create_request(
    request_type='deletion',
    data_subject={
        'email': 'user@example.com',
        'identifiers': [{'type': 'user_id', 'value': '12345'}]
    },
    legal_basis='GDPR_Article_17_1a',
    scope={
        'data_categories': ['personal_data'],
        'include_backups': True
    }
)

print(f'Request created: {request.id}')

# 상태 확인
status = client.get_request(request.id)
print(f'Status: {status.status}')

5.9 다음 단계

이 장에서는 WIA-LEG-009 Phase 2의 API 인터페이스를 상세히 살펴보았습니다. 다음 장에서는 블록체인을 사용한 암호학적 삭제 검증인 Phase 3를 다룹니다.