📚 Chapter 5: Phase 2 - API Interface Standard

This chapter defines the RESTful API endpoints for managing learner profiles, courses, content, and assessments. These APIs enable platform integration and interoperability.

---

5.1 API Design Principles

• RESTful: Standard HTTP methods and status codes
• JSON: All request/response bodies in JSON format
• Versioned: API versioning via URL path (/v1/)
• Authenticated: OAuth 2.0 bearer tokens
• Paginated: Standard pagination for list endpoints

5.1.1 Base URL

https://api.wiastandards.com/edu/v1

---

5.2 Learner Profile Endpoints

// Request
POST /profiles
Content-Type: application/json
Authorization: Bearer {token}

{
  "learner_info": {
    "name": "Kim Minjun",
    "institution_id": "INST-001"
  },
  "display_preferences": {
    "screen_reader": {
      "enabled": true,
      "reader": "nvda"
    },
    "text_settings": {
      "font_size": "large",
      "dyslexia_font": true
    }
  },
  "content_preferences": {
    "captions": true,
    "text_to_speech": { "enabled": true }
  }
}

// Response 201 Created
{
  "profile_id": "EDU-2025-ABCD-1234",
  "schema_version": "1.0.0",
  "created_at": "2025-01-15T10:30:00Z",
  "learner_info": { ... },
  "display_preferences": { ... },
  "content_preferences": { ... }
}

---

5.3 Course Endpoints

// Match learner to course
POST /courses/COURSE-001/match
{
  "profile_id": "EDU-2025-ABCD-1234"
}

// Response
{
  "course_id": "COURSE-001",
  "profile_id": "EDU-2025-ABCD-1234",
  "matched_accommodations": {
    "extended_time": true,
    "screen_reader_compatible": true,
    "captions_available": true,
    "text_to_speech_enabled": true
  },
  "unmet_needs": [
    {
      "need": "braille_materials",
      "status": "not_available",
      "alternative": "screen_reader_with_braille_display"
    }
  ],
  "recommendations": [
    "Enable high contrast mode in course settings",
    "Request sign language interpreter for live sessions"
  ]
}

---

5.4 Content Endpoints

// Check content accessibility
GET /content/CONTENT-001/check

// Response
{
  "content_id": "CONTENT-001",
  "wcag_level": "AA",
  "passed": true,
  "score": 95,
  "issues": [
    {
      "criterion": "1.4.3",
      "description": "Some text has contrast ratio of 4.3:1",
      "severity": "minor",
      "location": "slide_12",
      "recommendation": "Increase text contrast to 4.5:1 or higher"
    }
  ],
  "features_detected": [
    "captions",
    "transcript",
    "structural_navigation",
    "alternative_text"
  ]
}

---

5.5 Assessment Endpoints

// Configure assessment accommodations for learner
POST /assessments/ASSESS-001/configure
{
  "profile_id": "EDU-2025-ABCD-1234",
  "accommodations": {
    "extended_time": 1.5,
    "breaks_allowed": true,
    "screen_reader": true,
    "text_to_speech": true
  }
}

// Response
{
  "session_id": "SESSION-001",
  "assessment_id": "ASSESS-001",
  "profile_id": "EDU-2025-ABCD-1234",
  "configured_settings": {
    "time_limit_minutes": 90,
    "original_time_minutes": 60,
    "multiplier": 1.5,
    "breaks_enabled": true,
    "break_duration_minutes": 10,
    "presentation": {
      "screen_reader_mode": true,
      "tts_enabled": true,
      "high_contrast": true
    }
  },
  "start_url": "https://assess.example.com/start?session=SESSION-001"
}

---

5.6 LTI Integration Endpoints

// LTI Custom Claims for Accessibility
{
  "https://wiastandards.com/edu/profile_id": "EDU-2025-ABCD-1234",
  "https://wiastandards.com/edu/extended_time": 1.5,
  "https://wiastandards.com/edu/screen_reader": true,
  "https://wiastandards.com/edu/captions": true,
  "https://wiastandards.com/edu/text_to_speech": true
}

---

5.7 Error Handling

Status Code	Meaning	Example
200	Success	Profile retrieved
201	Created	Profile created
400	Bad Request	Invalid schema
401	Unauthorized	Invalid token
403	Forbidden	Insufficient permissions
404	Not Found	Profile not found
409	Conflict	Profile already exists
422	Unprocessable	Validation failed
500	Server Error	Internal error

// Error Response Format
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid profile data",
    "details": [
      {
        "field": "display_preferences.screen_reader.reader",
        "error": "Must be one of: nvda, jaws, voiceover, talkback"
      }
    ],
    "request_id": "req_abc123"
  }
}

---

5.8 Chapter Summary