# WIA-EDU-019 Digital Content Standard v1.1

## Phase 2: API Interface & Integration

**Status:** ✅ Complete
**Version:** 1.1.0
**Date:** 2025-01-15
**Philosophy:** 弘익人間 (Benefit All Humanity)

---

## 1. Overview

Phase 2 defines the API interfaces for creating, managing, distributing, and consuming WIA-compliant digital content. This specification ensures interoperability between content management systems, learning platforms, and end-user applications.

## 2. Scope

Phase 2 covers:
- RESTful API specifications
- Authentication and authorization
- Content CRUD operations
- Search and discovery APIs
- Analytics and tracking
- Integration with learning standards (SCORM, xAPI, LTI)

## 3. API Architecture

### 3.1 Base URL Structure

```
https://api.example.com/wia/v1/
```

### 3.2 HTTP Methods

| Method | Purpose | Idempotent |
|--------|---------|------------|
| GET | Retrieve resources | Yes |
| POST | Create resources | No |
| PUT | Update/replace resources | Yes |
| PATCH | Partial update | No |
| DELETE | Remove resources | Yes |

## 4. Authentication

### 4.1 OAuth 2.0

All API endpoints MUST support OAuth 2.0 authentication:

```http
POST /oauth/token
Content-Type: application/json

{
  "grant_type": "client_credentials",
  "client_id": "your-client-id",
  "client_secret": "your-client-secret"
}
```

**Response:**
```json
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}
```

### 4.2 API Key Authentication

For simple use cases, API key authentication MAY be supported:

```http
GET /content/123
Authorization: Bearer YOUR_API_KEY
```

## 5. Content API

### 5.1 List Content

```http
GET /content
Authorization: Bearer {access_token}
```

**Query Parameters:**
- `limit` (integer): Number of results (default: 20, max: 100)
- `offset` (integer): Pagination offset
- `type` (string): Filter by content type (video, audio, interactive)
- `language` (string): Filter by language code (en, ko, es)
- `search` (string): Full-text search query

**Response:**
```json
{
  "total": 150,
  "limit": 20,
  "offset": 0,
  "items": [
    {
      "id": "content-123",
      "title": "Introduction to Digital Content",
      "type": "video",
      "language": "en",
      "duration": 900,
      "createdAt": "2025-01-15T10:00:00Z",
      "updatedAt": "2025-01-20T15:30:00Z"
    }
  ]
}
```

### 5.2 Get Content Details

```http
GET /content/{id}
Authorization: Bearer {access_token}
```

**Response:**
```json
{
  "id": "content-123",
  "title": "Introduction to Digital Content",
  "description": "Comprehensive guide...",
  "type": "video",
  "format": "mp4",
  "language": "en",
  "duration": 900,
  "fileSize": 245760000,
  "url": "https://cdn.example.com/content-123.mp4",
  "thumbnail": "https://cdn.example.com/thumb-123.jpg",
  "metadata": {
    "creator": "Jane Smith",
    "subject": ["Education", "Technology"],
    "wcagLevel": "AA"
  },
  "accessibility": {
    "captions": ["en", "ko", "es"],
    "audioDescription": true,
    "transcript": true
  },
  "license": {
    "type": "CC BY 4.0",
    "url": "https://creativecommons.org/licenses/by/4.0/"
  }
}
```

### 5.3 Create Content

```http
POST /content
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "title": "New Content",
  "description": "Description...",
  "type": "video",
  "language": "en",
  "file": "base64_encoded_content_or_url",
  "metadata": { ... },
  "accessibility": { ... }
}
```

**Response:** `201 Created`
```json
{
  "id": "content-456",
  "title": "New Content",
  "status": "processing",
  "createdAt": "2025-01-20T16:00:00Z"
}
```

### 5.4 Update Content

```http
PUT /content/{id}
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "title": "Updated Title",
  "description": "Updated description..."
}
```

**Response:** `200 OK`

### 5.5 Delete Content

```http
DELETE /content/{id}
Authorization: Bearer {access_token}
```

**Response:** `204 No Content`

## 6. Search API

### 6.1 Full-Text Search

```http
POST /search
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "query": "digital content standards",
  "filters": {
    "type": ["video", "interactive"],
    "language": ["en", "ko"],
    "wcagLevel": "AA"
  },
  "sort": {
    "field": "relevance",
    "order": "desc"
  },
  "limit": 20,
  "offset": 0
}
```

**Response:**
```json
{
  "total": 42,
  "results": [
    {
      "id": "content-123",
      "title": "Introduction to Digital Content",
      "score": 0.95,
      "highlights": {
        "title": "Introduction to <em>Digital Content</em>",
        "description": "...comprehensive <em>standards</em>..."
      }
    }
  ]
}
```

## 7. Analytics API

### 7.1 Track Usage

```http
POST /analytics/track
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "contentId": "content-123",
  "userId": "user-456",
  "event": "view",
  "timestamp": "2025-01-20T16:30:00Z",
  "metadata": {
    "duration": 450,
    "completion": 0.5,
    "device": "mobile"
  }
}
```

**Response:** `201 Created`

### 7.2 Get Analytics

```http
GET /analytics/content/{id}
Authorization: Bearer {access_token}
```

**Response:**
```json
{
  "contentId": "content-123",
  "period": "2025-01",
  "views": 1523,
  "uniqueUsers": 487,
  "averageDuration": 845,
  "completionRate": 0.73,
  "demographics": {
    "countries": {"US": 423, "KR": 189},
    "devices": {"desktop": 612, "mobile": 398, "tablet": 513}
  }
}
```

## 8. Learning Standards Integration

### 8.1 xAPI (Experience API)

```http
POST /xapi/statements
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "actor": {
    "mbox": "mailto:student@example.com",
    "name": "Jane Student"
  },
  "verb": {
    "id": "http://adlnet.gov/expapi/verbs/completed",
    "display": {"en-US": "completed"}
  },
  "object": {
    "id": "https://example.com/content-123",
    "objectType": "Activity"
  },
  "result": {
    "score": {"scaled": 0.95},
    "success": true,
    "completion": true,
    "duration": "PT15M"
  }
}
```

### 8.2 LTI 1.3 Integration

Support for IMS Global LTI 1.3 standard for seamless LMS integration.

## 9. Webhooks

### 9.1 Register Webhook

```http
POST /webhooks
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "url": "https://your-app.com/webhook",
  "events": ["content.created", "content.updated", "content.deleted"],
  "secret": "your-webhook-secret"
}
```

## 10. Rate Limiting

- **Rate Limit:** 1000 requests per hour
- **Headers:**
  - `X-RateLimit-Limit: 1000`
  - `X-RateLimit-Remaining: 999`
  - `X-RateLimit-Reset: 1642694400`

## 11. Error Handling

### 11.1 Error Response Format

```json
{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "The request was invalid or cannot be served",
    "details": [
      {
        "field": "title",
        "message": "Title is required"
      }
    ]
  }
}
```

### 11.2 HTTP Status Codes

- `200 OK`: Success
- `201 Created`: Resource created
- `400 Bad Request`: Invalid request
- `401 Unauthorized`: Authentication required
- `403 Forbidden`: Insufficient permissions
- `404 Not Found`: Resource not found
- `429 Too Many Requests`: Rate limit exceeded
- `500 Internal Server Error`: Server error

---

**WIA-EDU-019 Phase 2 Complete**
弘益人間 · Benefit All Humanity

© 2025 WIA - World Certification Industry Association
MIT License