# WIA-EDU-008 Digital Textbook Standard v1.1 ## Phase 2: API Interface & Integration **Status:** ✅ Complete **Version:** 1.1.0 **Date:** 2025-02-15 **Philosophy:** 弘益人間 (Benefit All Humanity) **Builds on:** v1.0 (Phase 1) --- ## 1. Overview Phase 2 extends the WIA Digital Textbook Standard with comprehensive API specifications for content delivery, user data management, and learning management system integration. This phase enables seamless integration across platforms and ecosystems. ## 2. RESTful API Specification ### 2.1 Base URL Structure ``` https://api.{provider}.com/wia/v1/ ``` ### 2.2 Core Endpoints #### Textbook Discovery and Metadata ``` GET /textbooks # List available textbooks GET /textbooks/{id} # Get textbook metadata GET /textbooks/{id}/toc # Get table of contents GET /textbooks/{id}/chapters # List chapters GET /textbooks/{id}/chapters/{num} # Get chapter content ``` #### Content Delivery ``` GET /textbooks/{id}/download # Download full EPUB GET /textbooks/{id}/cover # Get cover image GET /textbooks/{id}/sample # Get sample chapters ``` #### User Data Management ``` GET /users/{userId}/library # User's textbook library POST /users/{userId}/library # Add textbook to library DELETE /users/{userId}/library/{id} # Remove from library ``` #### Annotations ``` GET /annotations # List user annotations POST /annotations # Create annotation GET /annotations/{id} # Get specific annotation PUT /annotations/{id} # Update annotation DELETE /annotations/{id} # Delete annotation ``` #### Reading Progress ``` GET /progress/{textbookId} # Get reading progress POST /progress/{textbookId} # Update reading progress ``` #### Analytics ``` GET /analytics/reading # Reading analytics GET /analytics/engagement # Engagement metrics GET /analytics/assessment # Assessment results ``` ### 2.3 Request/Response Format All requests and responses use JSON with UTF-8 encoding. **Standard Headers:** ``` Content-Type: application/json Accept: application/json Authorization: Bearer {access_token} X-WIA-Standard: WIA-EDU-008 X-WIA-Version: 1.1 ``` ### 2.4 Example: Get Textbook Metadata **Request:** ```http GET /textbooks/978-3-16-148410-0 HTTP/1.1 Host: api.textbooks.com Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9... Accept: application/json ``` **Response:** ```json { "id": "978-3-16-148410-0", "wiaId": "WIA-EDU-008-TB-00123456", "title": "Introduction to Physics", "subtitle": "Mechanics and Thermodynamics", "authors": [ { "name": "Dr. Jane Smith", "orcid": "0000-0002-1825-0097" }, { "name": "Dr. John Doe", "orcid": "0000-0001-5678-1234" } ], "publisher": { "name": "Academic Press", "wiaId": "WIA-PUB-00789" }, "edition": "3rd Edition", "publicationDate": "2025-01-15", "language": ["en", "es"], "isbn": "978-3-16-148410-0", "format": "EPUB3", "fileSize": 127834289, "pageCount": 456, "chapterCount": 15, "wiaCompliant": true, "wcagLevel": "AA", "subjects": ["Physics", "Mechanics", "Thermodynamics"], "educationLevel": "Grade 11-12", "features": { "hasVideo": true, "hasAudio": true, "hasInteractive": true, "hasMathML": true, "hasAssessments": true }, "links": { "download": "/textbooks/978-3-16-148410-0/download", "cover": "/textbooks/978-3-16-148410-0/cover", "sample": "/textbooks/978-3-16-148410-0/sample", "toc": "/textbooks/978-3-16-148410-0/toc" } } ``` ## 3. Authentication & Authorization ### 3.1 OAuth 2.0 Support (Required) Implement OAuth 2.0 Authorization Code Flow with PKCE. **Authorization Endpoint:** ``` GET https://auth.provider.com/oauth/authorize? response_type=code& client_id=YOUR_CLIENT_ID& redirect_uri=https://yourapp.com/callback& scope=read:textbooks write:annotations read:progress& state=xyz123& code_challenge=CHALLENGE& code_challenge_method=S256 ``` **Token Endpoint:** ```http POST /oauth/token HTTP/1.1 Content-Type: application/x-www-form-urlencoded grant_type=authorization_code& code=AUTH_CODE& client_id=YOUR_CLIENT_ID& redirect_uri=https://yourapp.com/callback& code_verifier=VERIFIER ``` **Token Response:** ```json { "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...", "token_type": "Bearer", "expires_in": 3600, "refresh_token": "def50200...", "scope": "read:textbooks write:annotations read:progress" } ``` ### 3.2 OpenID Connect Support (Optional) For user identity management, support OpenID Connect. ### 3.3 LTI 1.3 Integration (Required for LMS) Implement IMS Global LTI 1.3 for learning management system integration. **LTI Launch:** - Deep linking for content selection - Grade passback via Assignment and Grade Services - Names and Role Provisioning Services ## 4. Annotation API Specification ### 4.1 Create Annotation **Request:** ```http POST /annotations HTTP/1.1 Content-Type: application/json Authorization: Bearer {token} { "textbookId": "978-3-16-148410-0", "chapterId": "chapter-05", "type": "highlight", "selector": { "type": "TextPositionSelector", "start": 1234, "end": 1456 }, "color": "#FFFF00", "note": "Important formula for exam", "tags": ["exam", "formulas", "chapter5"], "visibility": "private" } ``` **Response:** ```json { "id": "anno-12345678", "created": "2025-12-25T10:30:00Z", "modified": "2025-12-25T10:30:00Z", "syncStatus": "synced", "links": { "self": "/annotations/anno-12345678" } } ``` ### 4.2 List Annotations ```http GET /annotations?textbookId=978-3-16-148410-0&chapter=chapter-05 HTTP/1.1 ``` **Response:** ```json { "total": 23, "page": 1, "perPage": 20, "annotations": [ { "id": "anno-12345678", "type": "highlight", "color": "#FFFF00", "note": "Important formula for exam", "created": "2025-12-25T10:30:00Z", "selector": {...} } ] } ``` ## 5. Learning Analytics API ### 5.1 xAPI Statement Endpoint ```http POST /xapi/statements HTTP/1.1 Content-Type: application/json X-Experience-API-Version: 1.0.3 { "actor": { "objectType": "Agent", "name": "Alice Johnson", "mbox": "mailto:alice@example.com" }, "verb": { "id": "http://adlnet.gov/expapi/verbs/completed", "display": {"en-US": "completed"} }, "object": { "objectType": "Activity", "id": "https://textbooks.com/physics/chapter-05", "definition": { "name": {"en-US": "Chapter 5: Newton's Laws"} } }, "result": { "completion": true, "success": true, "score": {"scaled": 0.92} } } ``` ## 6. LMS Integration ### 6.1 Grade Passback ```http POST /lms/grades HTTP/1.1 Content-Type: application/json { "lmsType": "canvas", "courseId": "PHYS101", "assignmentId": "quiz-ch5", "userId": "user123", "score": 0.92, "maxScore": 1.0, "timestamp": "2025-12-25T11:45:00Z", "comment": "Excellent understanding of Newton's Laws" } ``` ## 7. Error Handling ### 7.1 Standard Error Response ```json { "error": { "code": "RESOURCE_NOT_FOUND", "message": "Textbook with ID 978-0-00-000000-0 not found", "details": { "requestId": "req-abc123", "timestamp": "2025-12-25T10:30:00Z" } } } ``` ### 7.2 HTTP Status Codes - 200: Success - 201: Created - 204: No Content - 400: Bad Request - 401: Unauthorized - 403: Forbidden - 404: Not Found - 429: Rate Limit Exceeded - 500: Internal Server Error ## 8. Rate Limiting ```http HTTP/1.1 200 OK X-RateLimit-Limit: 1000 X-RateLimit-Remaining: 987 X-RateLimit-Reset: 1735132800 ``` ## 9. API Versioning APIs MUST support versioning via URL path: ``` /v1/textbooks /v2/textbooks ``` Backward compatibility MUST be maintained for at least 24 months. --- **Philosophy:** 弘益人間 · Benefit All Humanity © 2025 WIA - World Certification Industry Association