# API Integration Skill --- name: api-integration description: Advanced skill for integrating child applications with MyJKKN parent app API. Use when developers need to generate API keys, fetch data from endpoints (students, staff, organizations), build UI components with API data, implement authentication, or set up data integration for child applications. Provides templates, working examples, and automated client generation. tags: api, integration, authentication, child-app, data-fetching --- ## Overview This skill enables efficient integration of child applications with the MyJKKN parent application API. It provides comprehensive guidance, automated tools, and ready-to-use templates for: - API key generation and management - Authentication and authorization flows - Data fetching from 16+ available endpoints - Building UI components (tables, dropdowns, forms) with API data - Implementing pagination, filtering, and search - Error handling and retry logic - TypeScript type safety - Performance optimization ## When to Use This Skill Invoke this skill when: - Setting up a new child application that needs MyJKKN data - Integrating API endpoints into existing applications - Generating API clients for different frameworks - Implementing data tables, dropdowns, or forms with API data - Debugging API authentication or data fetching issues - Optimizing API calls and reducing redundant requests - Creating TypeScript-safe API integrations - Building search and filter functionality with API data ## Quick Start Workflow ### 1. Generate API Key First, understand the API key generation process: 1. Navigate to System → API Management in MyJKKN parent app 2. Click "Generate New API Key" 3. Provide a descriptive name (e.g., "Mobile App Production") 4. Set expiration date (optional, recommended for production keys) 5. Copy the generated key immediately (shown only once) 6. Store securely in environment variables **Key Format**: `jk_{randomString}_{timestamp}` **Security Notes**: - Plain text keys are never stored in the database - Only SHA-256 hash is persisted - Keys can be activated\/deactivated without deletion - Monitor `last_used_at` timestamp for usage tracking ### 2. Set Up Environment Configure environment variables in child application: ```env # .env.local or .env NEXT_PUBLIC_MYJKKN_API_URL=https:\/\/jkkn.ai\/api MYJKKN_API_KEY=jk_xxxxx_xxxxx ``` **Important**: - Use `NEXT_PUBLIC_` prefix only if key needs to be exposed to client-side - Prefer server-side API calls for sensitive operations - Never commit API keys to version control ### 3. Generate API Client Use the provided script to generate framework-specific API client: ```bash # React\/Next.js client with TypeScript python scripts\/generate_api_client.py --framework nextjs --output .\/lib\/api # Vanilla JavaScript client python scripts\/generate_api_client.py --framework vanilla --output .\/src\/api # Express.js backend client python scripts\/generate_api_client.py --framework express --output .\/services ``` Alternatively, use the pre-built templates in `assets\/` directory. ### 4. Test Connection Verify API key and connectivity: ```bash # Test API endpoint python scripts\/test_endpoint.py --endpoint students --key jk_xxxxx_xxxxx # Test with pagination python scripts\/test_endpoint.py --endpoint students --key jk_xxxxx_xxxxx --page 1 --limit 10 ``` ## Available API Endpoints MyJKKN provides 16+ REST API endpoints organized by domain: ### Students API - `GET \/api\/api-management\/students` - List students (paginated) - `GET \/api\/api-management\/students\/{id}` - Get student details **Filters**: `institution_id`, `department_id`, `program_id`, `is_profile_complete`, `search` ### Staff API - `GET \/api\/api-management\/staff` - List staff (paginated) - `GET \/api\/api-management\/staff\/{id}` - Get staff details - `GET \/api\/api-management\/staff?all=true` - Fetch all staff (no pagination) **Filters**: `institution_id`, `department_id`, `category_id`, `is_active`, `search` ### Organization API - `GET \/api\/api-management\/organizations\/institutions` - List institutions - `GET \/api\/api-management\/organizations\/departments` - List departments - `GET \/api\/api-management\/organizations\/programs` - List programs - `GET \/api\/api-management\/organizations\/degrees` - List degrees - `GET \/api\/api-management\/organizations\/courses` - List courses - `GET \/api\/api-management\/organizations\/semesters` - List semesters **Each endpoint supports**: Pagination, filtering by hierarchy (institution → degree → department → program), active status filtering, and search. **Detailed Documentation**: See `references\/api_endpoints.md` for complete endpoint specifications, request\/response formats, and examples. ## Authentication All API requests require Bearer token authentication: ```typescript headers: { 'Authorization': `Bearer ${apiKey}`, 'Accept': 'application\/json' } ``` **Authentication Flow**: 1. Client sends API key in Authorization header 2. Server hashes the provided key using SHA-256 3. Server verifies hash against database 4. Server checks key expiration and active status 5. Server validates read\/write permissions 6. Request proceeds if all checks pass **Error Responses**: - `401 Unauthorized` - Missing, invalid, or expired API key - `403 Forbidden` - Insufficient permissions (e.g., no read access) **Reference**: See `references\/authentication_guide.md` for detailed auth implementation. ## Common Integration Patterns ### Pattern 1: Paginated Data Table Fetch paginated data for data tables with search and filters: ```typescript import { useState, useEffect } from 'react'; import { apiClient } from '@\/lib\/api\/client'; export function useStudents(filters) { const [data, setData] = useState([]); const [loading, setLoading] = useState(false); const [pagination, setPagination] = useState({ page: 1, limit: 10 }); useEffect(() => { const fetchStudents = async () => { setLoading(true); try { const response = await apiClient.students.list({ ...filters, page: pagination.page, limit: pagination.limit }); setData(response.data); setPagination(prev => ({ ...prev, total: response.metadata.total })); } catch (error) { console.error('Failed to fetch students:', error); } finally { setLoading(false); } }; fetchStudents(); }, [filters, pagination.page, pagination.limit]); return { data, loading, pagination, setPagination }; } ``` ### Pattern 2: Dropdown with API Data Populate dropdown\/select components with API data: ```typescript import { useEffect, useState } from 'react'; import { apiClient } from '@\/lib\/api\/client'; export function useDepartments(institutionId: string) { const [departments, setDepartments] = useState([]); const [loading, setLoading] = useState(false); useEffect(() => { if (!institutionId) return; const fetchDepartments = async () => { setLoading(true); try { \/\/ Fetch all departments without pagination const response = await apiClient.organizations.departments.list({ institution_id: institutionId, limit: 1000 \/\/ Large limit to get all }); setDepartments(response.data); } catch (error) { console.error('Failed to fetch departments:', error); } finally { setLoading(false); } }; fetchDepartments(); }, [institutionId]); return { departments, loading }; } \/\/ Usage in component function MyForm() { const { departments, loading } = useDepartments(selectedInstitution); return ( { setInstitution(e.target.value); setDepartment(''); \/\/ Reset dependent fields setProgram(''); }}> {institutions.map(inst => (