Phase 2: API 인터페이스

5.1 API 인터페이스 개요

Phase 2는 개발자가 WIA-ART-001 표준과 프로그래밍 방식으로 상호작용할 수 있는 인터페이스를 정의합니다. REST API 엔드포인트, TypeScript SDK, 인증 메커니즘이 포함됩니다.

5.2 TypeScript SDK

5.2.1 설치

# npm
npm install @wia/art-001-sdk

# yarn
yarn add @wia/art-001-sdk

# pnpm
pnpm add @wia/art-001-sdk

5.2.2 초기화

import { WIAART001, DigitalArtSDK } from '@wia/art-001-sdk';

const sdk = new WIAART001({
  apiKey: 'wia_art_sk_...',
  endpoint: 'https://api.wia.org/art-001/v1',
  timeout: 30000,
  enableValidation: true,
  enableCaching: true
});

5.2.3 타입 정의

// 아트워크 인터페이스
export interface Artwork {
  id: string;
  version: string;
  metadata: ArtworkMetadata;
  content: ArtworkContent;
  provenance: ProvenanceChain;
  createdAt: Date;
  updatedAt: Date;
}

// 메타데이터 인터페이스
export interface ArtworkMetadata {
  title: string;
  creator: CreatorInfo;
  description?: string;
  creationDate?: Date;
  colorSpace: ColorSpace;
  dimensions?: Dimensions;
  keywords?: string[];
  license?: LicenseInfo;
}

// 색 공간 타입
export type ColorSpace = 
  | 'sRGB' 
  | 'Adobe RGB' 
  | 'ProPhoto RGB' 
  | 'Display P3';

// 품질 등급 타입
export type QualityTier = 
  | 'archival' 
  | 'professional' 
  | 'web' 
  | 'preview';

5.2.4 핵심 메서드

// 작품 생성
const artwork = await sdk.create({
  title: '디지털 풍경',
  creator: { name: '김아티스트' },
  colorSpace: 'Adobe RGB'
});

// 작품 조회
const artwork = await sdk.read('art_2xK9mN3pQr5tV7wY');

// 작품 수정
const updated = await sdk.update('art_id', {
  metadata: { description: '수정된 설명' }
});

// 작품 삭제
await sdk.delete('art_id');

// 검증
const result = await sdk.validate(artworkData);

// 내보내기
const buffer = await sdk.export('art_id', {
  format: 'PNG',
  quality: 'web',
  embedMetadata: true
});

5.3 REST API 엔드포인트

5.3.1 작품 생성

// 요청
POST /api/v1/digital-art
Content-Type: application/json
Authorization: Bearer wia_art_sk_...

{
  "title": "디지털 풍경 #42",
  "creator": {
    "name": "김아티스트",
    "contact": "artist@example.com"
  },
  "colorSpace": "Adobe RGB",
  "description": "초현실적 풍경화"
}

// 응답 (201 Created)
{
  "success": true,
  "data": {
    "id": "art_2xK9mN3pQr5tV7wY",
    "status": "created",
    "uploadUrl": "https://upload.wia.org/...",
    "expiresAt": "2025-01-15T11:30:00Z"
  }
}

5.3.2 작품 조회

// 요청
GET /api/v1/digital-art/art_2xK9mN3pQr5tV7wY
Authorization: Bearer wia_art_sk_...

// 응답 (200 OK)
{
  "success": true,
  "data": {
    "id": "art_2xK9mN3pQr5tV7wY",
    "version": "1.0",
    "metadata": {
      "title": "디지털 풍경 #42",
      "creator": { "name": "김아티스트" },
      "colorSpace": "Adobe RGB"
    },
    "content": {
      "primary": {
        "format": "PNG",
        "url": "https://cdn.wia.org/...",
        "size": 15728640
      }
    }
  }
}

5.3.3 작품 검증

// 요청
POST /api/v1/digital-art/validate
Content-Type: application/json

{
  "metadata": {
    "title": "테스트 작품",
    "creator": { "name": "테스트" },
    "colorSpace": "sRGB"
  }
}

// 응답 (200 OK)
{
  "valid": true,
  "complianceLevel": "full",
  "checks": [
    { "rule": "metadata.title.required", "passed": true },
    { "rule": "metadata.creator.required", "passed": true },
    { "rule": "metadata.colorSpace.valid", "passed": true }
  ],
  "recommendations": [
    "description 필드 추가 권장"
  ]
}

5.3.4 작품 검색

// 쿼리 파라미터
- q: 전문 검색 쿼리
- creator: 작가 ID 필터
- colorSpace: 색 공간 필터
- format: 파일 형식 필터
- dateFrom/dateTo: 생성일 범위
- limit: 페이지당 결과 수 (기본 20, 최대 100)
- offset: 페이징 오프셋

// 예시
GET /api/v1/digital-art?q=풍경&colorSpace=sRGB&limit=10

// 응답
{
  "results": [...],
  "pagination": {
    "total": 42,
    "limit": 10,
    "offset": 0,
    "hasMore": true
  }
}

5.4 인증

5.4.1 API 키 인증

// 헤더 방식 (권장)
Authorization: Bearer wia_art_sk_1234567890abcdef

// API 키 형식
- 프로덕션: wia_art_sk_... (secret key)
- 테스트: wia_art_test_... (test key)
- 퍼블릭: wia_art_pk_... (public key, 읽기 전용)

5.4.2 OAuth 2.0

// 1단계: 인증 요청
GET /oauth/authorize
  ?client_id=YOUR_CLIENT_ID
  &redirect_uri=https://yourapp.com/callback
  &response_type=code
  &scope=art:read art:write

// 2단계: 토큰 교환
POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=AUTH_CODE
&redirect_uri=https://yourapp.com/callback
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET

// 3단계: 토큰 사용
Authorization: Bearer ACCESS_TOKEN

5.4.3 권한 범위 (Scope)

5.5 요청 제한

5.5.1 등급별 제한

5.5.2 응답 헤더

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 850
X-RateLimit-Reset: 1705330800
X-RateLimit-RetryAfter: 120

5.5.3 제한 초과 처리

// 429 Too Many Requests
{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "요청 제한을 초과했습니다",
    "retryAfter": 120
  }
}

// 재시도 로직
async function requestWithRetry(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error.status === 429) {
        const delay = error.retryAfter || 60;
        await sleep(delay * 1000);
      } else {
        throw error;
      }
    }
  }
}

5.6 에러 처리

5.6.1 에러 응답 형식

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "요청 검증 실패",
    "details": [
      {
        "field": "metadata.colorSpace",
        "issue": "유효하지 않은 색 공간",
        "expected": "sRGB | Adobe RGB | ProPhoto RGB | Display P3",
        "received": "RGB"
      }
    ],
    "requestId": "req_abc123",
    "timestamp": "2025-01-15T10:30:00Z"
  }
}

5.6.2 HTTP 상태 코드

한국 사례 및 실무 적용

한국 디지털 아트 산업에서 WIA-ART-001 표준이 어떻게 적용되고 있는지 실제 사례를 통해 살펴봅니다.

글로벌 시장 진출 사례

WIA 표준을 활용한 한국 디지털 아티스트의 해외 진출이 증가하고 있습니다:

• 북미 시장: WIA 호환 포트폴리오로 Artstation, Behance에서 채용 기회 3배 증가
• 일본 시장: 메타데이터 다국어 지원으로 Pixiv, NicoNico 진출 용이
• 유럽 시장: GDPR 준수 메타데이터로 EU 플랫폼 접근성 향상
• 동남아 시장: 표준화된 라이선스 정보로 저작권 보호 강화

실무 구현 가이드

프로덕션 환경에서 이 기능을 안전하고 효율적으로 구현하기 위한 실무 지침입니다.

성능 최적화 전략

대용량 파일 처리

// TypeScript 예제: 청크 업로드로 대용량 파일 처리
async function uploadLargeArtwork(file: File) {
  const CHUNK_SIZE = 5 * 1024 * 1024; // 5MB chunks
  const totalChunks = Math.ceil(file.size / CHUNK_SIZE);
  
  for (let i = 0; i < totalChunks; i++) {
    const start = i * CHUNK_SIZE;
    const end = Math.min(start + CHUNK_SIZE, file.size);
    const chunk = file.slice(start, end);
    
    await uploadChunk(chunk, i, totalChunks);
  }
  
  // 모든 청크 업로드 후 병합 요청
  await finalizeUpload(file.name);
}

캐싱 전략

// Redis를 활용한 메타데이터 캐싱
const cacheKey = `artwork:${artworkId}:metadata`;
const ttl = 3600; // 1시간

// 캐시에서 먼저 조회
let metadata = await redis.get(cacheKey);

if (!metadata) {
  // 캐시 미스 시 DB에서 조회
  metadata = await db.getArtworkMetadata(artworkId);
  
  // 캐시에 저장
  await redis.setex(cacheKey, ttl, JSON.stringify(metadata));
}

return JSON.parse(metadata);

보안 강화 방안

파일 검증 프로세스

// 안전한 파일 업로드 검증
function validateUpload(file: File, metadata: ArtworkMetadata): ValidationResult {
  const checks = [
    // 1. MIME 타입 검증
    validateMimeType(file.type, metadata.format),
    
    // 2. 파일 크기 제한
    validateFileSize(file.size, MAX_FILE_SIZE),
    
    // 3. 파일 내용 검사 (매직 넘버)
    validateFileContent(file),
    
    // 4. 바이러스 스캔
    await scanForVirus(file),
    
    // 5. 메타데이터 스키마 검증
    validateSchema(metadata, WIA_ART_SCHEMA)
  ];
  
  return {
    valid: checks.every(c => c.passed),
    errors: checks.filter(c => !c.passed).map(c => c.error)
  };
}

에러 처리 및 복구

프로덕션 환경에서 발생할 수 있는 다양한 오류 상황에 대한 처리 전략:

고급 주제 및 최신 트렌드

AI 생성 아트 지원

AI 도구로 생성된 작품을 위한 특별한 메타데이터 필드:

{
  "aiGeneration": {
    "model": "Stable Diffusion XL",
    "version": "1.0",
    "prompt": "a serene Korean landscape in the style of traditional ink painting",
    "negativePrompt": "modern buildings, cars, people",
    "seed": 42,
    "steps": 50,
    "cfg_scale": 7.5,
    "sampler": "DPM++ 2M Karras",
    "humanContribution": {
      "promptDesign": 100,
      "postProcessing": 80,
      "selection": 100
    },
    "trainingDataConsent": true,
    "ethicalConsiderations": "No copyrighted content used in training"
  }
}

블록체인 통합

NFT 및 분산 저장소와의 통합 예제:

// WIA-BLOCKCHAIN 표준과 연동
async function mintAsNFT(artwork: Artwork) {
  // 1. IPFS에 작품 업로드
  const ipfsHash = await ipfs.add(artwork.content.primary);
  
  // 2. WIA 메타데이터를 NFT 메타데이터로 변환
  const nftMetadata = {
    name: artwork.metadata.title,
    description: artwork.metadata.description,
    image: `ipfs://${ipfsHash}`,
    attributes: [
      { trait_type: "Artist", value: artwork.metadata.creator.name },
      { trait_type: "Creation Date", value: artwork.metadata.creationDate },
      { trait_type: "Medium", value: artwork.metadata.medium }
    ],
    wia_standard: "WIA-ART-001",
    wia_version: "1.0",
    wia_artwork_id: artwork.id
  };
  
  // 3. 스마트 계약으로 NFT 발행
  const nft = await contract.mint(metadata, { value: mintingFee });
  
  // 4. 출처 정보에 NFT 정보 추가
  await updateProvenance(artwork.id, {
    type: "nft_minting",
    blockchain: "Ethereum",
    contract: contract.address,
    tokenId: nft.tokenId,
    ipfsHash: ipfsHash
  });
}

웹3 통합 및 분산 저장

중앙화된 서버 없이 작품을 분산 저장하고 관리하는 방법:

• IPFS: 작품 원본을 불변 저장소에 보관
• Filecoin: 장기 보존을 위한 유료 스토리지
• Arweave: 영구 저장을 위한 블록위브 기술
• Ceramic Network: 분산 메타데이터 관리

5.7 장 요약

복습 문제

1. SDK 초기화 시 필수 설정은 무엇인가요?
2. 작품 검증 API의 역할을 설명하세요.
3. OAuth 2.0 인증 흐름을 3단계로 설명하세요.
4. 429 에러 발생 시 어떻게 처리해야 하나요?