# WIA-EDU-012 Micro-Credential Standard v1.1

## Phase 2: API Interface & Integration

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

---

## 1. Overview

Phase 2 defines standardized APIs for issuing, managing, verifying, and sharing micro-credentials. This ensures interoperability between different platforms and enables integration with learning management systems, HR platforms, and credential wallets.

## 2. API Architecture

### 2.1 RESTful API Principles

- Resource-oriented design
- HTTP methods: GET, POST, PUT, DELETE
- JSON request/response format
- Stateless authentication
- HATEOAS for discoverability

### 2.2 Base URL Structure

```
https://api.wia.org/edu-012/v1
```

### 2.3 Authentication

All API requests require authentication using Bearer tokens:

```http
Authorization: Bearer <access_token>
```

## 3. Credential Issuance API

### 3.1 Issue New Credential

**Endpoint:** `POST /credentials`

**Request:**
```json
{
  "recipientId": "did:example:learner123",
  "recipientEmail": "learner@example.com",
  "achievementId": "https://wia.org/achievements/micro-cred-expert",
  "issuanceDate": "2025-01-15T00:00:00Z",
  "evidence": [
    {
      "type": "Portfolio",
      "url": "https://example.com/portfolio"
    }
  ],
  "competencies": [
    {
      "framework": "ESCO",
      "competencyId": "S1.2.3",
      "level": "advanced"
    }
  ]
}
```

**Response:**
```json
{
  "credentialId": "urn:uuid:91537dba-56cb-11ec-a1c3-0b40de2a2a74",
  "status": "issued",
  "verificationUrl": "https://wia.org/verify/91537dba",
  "createdAt": "2025-01-15T10:30:00Z"
}
```

### 3.2 Batch Issuance

**Endpoint:** `POST /credentials/batch`

Allows issuing multiple credentials in a single request.

## 4. Credential Verification API

### 4.1 Verify Credential

**Endpoint:** `GET /credentials/{id}/verify`

**Response:**
```json
{
  "valid": true,
  "credentialId": "urn:uuid:91537dba-56cb-11ec-a1c3-0b40de2a2a74",
  "issuer": "WIA Academy",
  "recipient": "learner@example.com",
  "issuedDate": "2025-01-15T00:00:00Z",
  "revoked": false,
  "expired": false,
  "signatureValid": true
}
```

### 4.2 Batch Verification

**Endpoint:** `POST /credentials/verify/batch`

## 5. Credential Management API

### 5.1 Retrieve Credential

**Endpoint:** `GET /credentials/{id}`

### 5.2 Update Credential

**Endpoint:** `PUT /credentials/{id}`

(Limited fields: status, privacy settings, expiration)

### 5.3 Revoke Credential

**Endpoint:** `DELETE /credentials/{id}`

or

**Endpoint:** `POST /credentials/{id}/revoke`

```json
{
  "reason": "Assessment invalidated",
  "effectiveDate": "2025-02-01T00:00:00Z"
}
```

## 6. Search & Discovery API

### 6.1 Search Credentials

**Endpoint:** `GET /credentials?<query_params>`

**Query Parameters:**
- `recipientId`: Filter by recipient
- `issuerId`: Filter by issuer
- `achievementId`: Filter by achievement type
- `competencyFramework`: Filter by competency framework
- `issuedAfter`: Date filter
- `limit`: Results per page
- `offset`: Pagination offset

### 6.2 Get Credential Statistics

**Endpoint:** `GET /credentials/stats`

## 7. Integration APIs

### 7.1 LMS Integration

**Endpoint:** `POST /integrations/lms/sync`

Synchronizes credential data with Learning Management Systems supporting LTI Advantage.

### 7.2 CLR Export

**Endpoint:** `GET /credentials/export/clr`

Exports credentials in IMS Comprehensive Learner Record format.

### 7.3 Open Badges Export

**Endpoint:** `GET /credentials/export/openbadges`

Exports pure Open Badges 3.0 format without WIA extensions.

## 8. Webhook Events

### 8.1 Subscribe to Events

**Endpoint:** `POST /webhooks`

```json
{
  "url": "https://client.example.com/webhook",
  "events": ["credential.issued", "credential.revoked"],
  "secret": "webhook_secret_key"
}
```

### 8.2 Event Types

- `credential.issued`
- `credential.verified`
- `credential.revoked`
- `credential.expired`
- `credential.renewed`

## 9. Rate Limiting

- Standard tier: 100 requests/minute
- Premium tier: 1000 requests/minute
- Batch operations count as single request

## 10. Error Handling

Standard HTTP status codes:
- 200: Success
- 201: Created
- 400: Bad Request
- 401: Unauthorized
- 403: Forbidden
- 404: Not Found
- 429: Rate Limit Exceeded
- 500: Internal Server Error

---

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