# WIA-EDU-014 Game-Based Learning Standard v1.1

## Phase 2: API Interface & Game Mechanics

**Status:** ✅ Complete
**Version:** 1.1.0
**Date:** 2025-12-25
**Philosophy:** 弘益人間 (Benefit All Humanity)

---

## 1. Overview

Phase 2 specifies RESTful APIs for game-based learning platforms, enabling standardized interaction between game clients, learning management systems, and analytics engines.

## 2. Scope

Phase 2 covers:
- RESTful API architecture
- Authentication and authorization
- Game catalog management
- Player profile operations
- Progress synchronization
- Achievement management
- Analytics collection
- Error handling and rate limiting

## 3. API Architecture

### 3.1 Base URL Structure
```
https://api.game-platform.com/v1/
```

### 3.2 HTTP Methods
- **GET**: Retrieve resources
- **POST**: Create new resources
- **PUT**: Replace existing resources
- **PATCH**: Update partial resource data
- **DELETE**: Remove resources

## 4. Authentication

### 4.1 OAuth 2.0
Recommended for third-party integrations:

```http
POST /v1/auth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code=AUTH_CODE&
client_id=CLIENT_ID&
client_secret=CLIENT_SECRET&
redirect_uri=REDIRECT_URI
```

Response:
```json
{
  "access_token": "eyJhbG...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "def5020...",
  "scope": "game:play analytics:read"
}
```

### 4.2 API Key Authentication
For server-to-server:
```http
GET /v1/games
Authorization: ApiKey YOUR_API_KEY
```

## 5. Game Catalog APIs

### 5.1 List Games
```http
GET /v1/games?subject=math&grade=7&difficulty=intermediate&limit=20&offset=0
```

Response:
```json
{
  "games": [...Phase 1 game metadata objects...],
  "pagination": {
    "total": 150,
    "limit": 20,
    "offset": 0,
    "next": "/v1/games?offset=20"
  }
}
```

### 5.2 Get Game Details
```http
GET /v1/games/{gameId}
```

### 5.3 Search Games
```http
GET /v1/games/search?q=algebra&language=en
```

## 6. Player Management APIs

### 6.1 Create Player
```http
POST /v1/players
Content-Type: application/json

{...Phase 1 player profile...}
```

### 6.2 Get Player Profile
```http
GET /v1/players/{playerId}
```

### 6.3 Update Preferences
```http
PATCH /v1/players/{playerId}/preferences
Content-Type: application/json

{
  "difficulty": "hard",
  "soundEnabled": false
}
```

## 7. Progress APIs

### 7.1 Save Progress
```http
POST /v1/progress
Content-Type: application/json

{...Phase 1 progress schema...}
```

### 7.2 Get Progress
```http
GET /v1/progress/{playerId}/{gameId}
```

### 7.3 List Player Progress
```http
GET /v1/progress/{playerId}
```

## 8. Achievement APIs

### 8.1 Award Achievement
```http
POST /v1/achievements
Content-Type: application/json

{
  "playerId": "player_xyz789",
  "achievementId": "badge_algebra_master",
  "earnedDate": "2025-12-25T14:30:00Z",
  "evidence": {...}
}
```

### 8.2 List Player Achievements
```http
GET /v1/achievements/{playerId}
```

### 8.3 Verify Achievement
```http
GET /v1/achievements/{achievementId}/verify?credential={credentialId}
```

## 9. Analytics APIs

### 9.1 Submit Events
```http
POST /v1/analytics/events
Content-Type: application/json

{
  "events": [
    {
      "eventType": "challenge_completed",
      "timestamp": "2025-12-25T14:30:00Z",
      "playerId": "player_xyz789",
      "gameId": "game_abc123",
      "data": {...}
    }
  ]
}
```

## 10. Error Handling

### 10.1 Error Response Format
```json
{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Human-readable error message",
    "details": "Additional context",
    "timestamp": "2025-12-25T14:30:00Z",
    "requestId": "req_12345"
  }
}
```

### 10.2 HTTP Status Codes
- 200: OK
- 201: Created
- 400: Bad Request
- 401: Unauthorized
- 403: Forbidden
- 404: Not Found
- 429: Too Many Requests
- 500: Internal Server Error

## 11. Rate Limiting

Responses include rate limit headers:
```http
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 2025-12-25T15:00:00Z
```

## 12. Versioning

API version in URL: `/v1/`, `/v2/`
Deprecation notice: minimum 12 months

---

**Next Phase:** Phase 3 defines real-time protocols for multiplayer and live updates.

弘益人間 · Benefit All Humanity
© 2025 WIA - MIT License