Chapter 5: Phase 2 - API Interface

5.1 REST API Architecture

WIA-UNI-011 APIs follow REST principles with resource-oriented design, standard HTTP methods, and stateless authentication. All endpoints return JSON with consistent error handling and comprehensive documentation via OpenAPI 3.0.

Base URL Structure

https://api.cultural-exchange.org/v2/
├── /events              # Cultural events
├── /participants        # Participants and artists
├── /heritage            # Heritage items
├── /organizations       # Organizations
├── /media               # Media assets
└── /analytics           # Analytics and reporting

5.2 Events API

Core Endpoints

Method	Endpoint	Description
GET	/events	List all events with filtering and pagination
GET	/events/{id}	Get specific event details
POST	/events	Create new event
PUT	/events/{id}	Update existing event
DELETE	/events/{id}	Delete event (soft delete)
GET	/events/{id}/participants	List event participants
POST	/events/{id}/participants	Add participant to event
GET	/events/{id}/media	List event media assets

List Events with Filtering

GET /events?type=music&startDate=2025-01-01®ion=both&limit=50

Response:
{
  "data": [
    {
      "eventId": "UNI-011-MUSIC-2025-001",
      "eventType": "music",
      "title": { "ko": "남북 음악 축제", "en": "Inter-Korean Music Festival" },
      "startDate": "2025-06-15T18:00:00+09:00",
      "location": { "name": { "en": "DMZ Peace Park" } }
    }
  ],
  "pagination": {
    "total": 127,
    "page": 1,
    "limit": 50,
    "pages": 3
  }
}

Query Parameters

• type - Filter by event type (arts, sports, music, festival, heritage, education)
• startDate - Events starting after this date (ISO 8601)
• endDate - Events ending before this date (ISO 8601)
• region - Filter by region (south, north, both)
• organization - Filter by organizing institution
• tags - Filter by tags (comma-separated)
• limit - Results per page (max 100)
• offset - Pagination offset

5.3 Authentication & Authorization

API access requires OAuth 2.0 authentication with JWT tokens. Different user roles have different permissions ensuring security and compliance.

Authentication Flow

1. Client requests token from auth server with credentials
2. Auth server validates and issues JWT access token
3. Client includes token in Authorization header for API requests
4. API validates token signature and permissions
5. API returns requested data or error

Role-Based Access Control

Role	Permissions	Use Cases
Public	Read public events, heritage	Website visitors, researchers
Organizer	Create/edit own events, add participants	Cultural institutions, NGOs
Ministry	Approve events, access sensitive data	Government agencies
Admin	Full access to all resources	System administrators

Example API Request with Authentication

POST /events
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...
Content-Type: application/json

{
  "eventType": "music",
  "title": { "ko": "서울 평화 콘서트", "en": "Seoul Peace Concert" },
  "startDate": "2025-08-01T19:00:00+09:00",
  "endDate": "2025-08-01T22:00:00+09:00",
  "location": {
    "name": { "en": "Seoul Olympic Stadium" },
    "coordinates": { "lat": 37.5151, "lng": 127.1223 }
  }
}

5.4 Heritage API

Heritage API enables documentation and discovery of Korean cultural heritage with rich metadata, regional variations, and UNESCO integration.

Heritage Endpoints

Method	Endpoint	Description
GET	/heritage	Search heritage items
GET	/heritage/{id}	Get heritage details
GET	/heritage/{id}/variations	Get regional variations
GET	/heritage/search	Full-text search
POST	/heritage	Document new heritage item
PUT	/heritage/{id}	Update heritage information

Heritage Search with Semantic Matching

GET /heritage/search?q=traditional+music&category=music®ion=both

Response:
{
  "results": [
    {
      "heritageId": "HER-KR-MUSIC-001",
      "name": { "ko": "아리랑", "en": "Arirang" },
      "category": "music",
      "unescoStatus": "registered",
      "matchScore": 0.95,
      "regionalVariations": 12
    },
    {
      "heritageId": "HER-KR-MUSIC-002",
      "name": { "ko": "판소리", "en": "Pansori" },
      "category": "music",
      "unescoStatus": "registered",
      "matchScore": 0.87,
      "regionalVariations": 5
    }
  ]
}

5.5 Media API

Media API manages photos, videos, audio recordings, and documents with proper rights management, versioning, and archival support.

Media Upload Flow

1. Request upload URL with media metadata
2. Upload file directly to storage (S3, etc.) using signed URL
3. Confirm upload completion with checksum verification
4. Media asset becomes available via API

Media Endpoints

POST /media/upload-url
{
  "filename": "peace-concert-2025.jpg",
  "type": "photo",
  "size": 2457600,
  "mimeType": "image/jpeg"
}

Response:
{
  "assetId": "MEDIA-2025-001",
  "uploadUrl": "https://storage.cultural-exchange.org/upload/...",
  "expiresIn": 3600
}

5.6 Analytics API

Analytics endpoints provide insights into cultural exchange trends, participation patterns, geographic distribution, and impact metrics.

Available Analytics

• Event Statistics: Events per month, type distribution, participant counts
• Participation Trends: Active organizations, artist involvement, audience engagement
• Geographic Analysis: Events by region, cross-border collaboration patterns
• Heritage Documentation: Items documented, preservation status, UNESCO progress
• Impact Metrics: Media reach, cultural exchange growth, policy influence

Example: Event Trend Analysis

GET /analytics/events/trends?period=2024-01-01:2025-12-31&granularity=month

Response:
{
  "period": { "start": "2024-01-01", "end": "2025-12-31" },
  "data": [
    { "month": "2024-01", "events": 12, "participants": 487 },
    { "month": "2024-02", "events": 15, "participants": 623 },
    ...
  ],
  "summary": {
    "totalEvents": 187,
    "totalParticipants": 8934,
    "averageParticipants": 47.8,
    "growthRate": 0.23
  }
}

5.7 Rate Limiting & Performance

Rate Limits

User Tier	Requests/Hour	Burst
Public	100	20
Organizer	1,000	100
Ministry	10,000	500
Admin	Unlimited	-

Response Headers

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1735110000

Caching Strategy

• GET requests cacheable with ETags and Cache-Control headers
• Event lists cached for 5 minutes
• Heritage data cached for 1 hour
• Media metadata cached for 24 hours
• Analytics cached based on data freshness requirements

5.8 SDK Development

Official SDKs simplify API integration in multiple programming languages with type safety, error handling, and best practices built-in.

Supported Languages

• JavaScript/TypeScript: npm package with full TypeScript definitions
• Python: pip package with type hints and async support
• Java: Maven artifact with Spring integration
• Go: Go module with context support

Example: TypeScript SDK Usage

import { CulturalExchangeClient } from '@wia/cultural-exchange';

const client = new CulturalExchangeClient({
  apiKey: process.env.WIA_API_KEY
});

// List upcoming music events
const events = await client.events.list({
  type: 'music',
  startDate: new Date('2025-06-01'),
  limit: 20
});

// Create new event
const newEvent = await client.events.create({
  eventType: 'music',
  title: { ko: '평화 콘서트', en: 'Peace Concert' },
  startDate: new Date('2025-08-01T19:00:00+09:00'),
  endDate: new Date('2025-08-01T22:00:00+09:00')
});

5.9 Error Handling

Consistent error responses enable robust client implementations with proper error handling and user feedback.

Standard Error Format

{
  "error": {
    "code": "INVALID_EVENT_TYPE",
    "message": "Event type 'concert' is not valid",
    "details": {
      "field": "eventType",
      "validValues": ["arts", "sports", "music", "festival", "heritage", "education"]
    },
    "timestamp": "2025-06-15T14:30:00Z",
    "requestId": "req-abc123"
  }
}

Chapter Summary