API Specifications

Overview

This document provides links and information about the Learnille platform’s API specifications.

API Documentation

Swagger/OpenAPI Specifications

The Learnille API is documented using OpenAPI 3.0 specification and is available through interactive Swagger UI documentation.

Production API Documentation

URL: https://api.learnille.com/docs
Swagger UI: Interactive API explorer
OpenAPI JSON: https://api.learnille.com/docs/openapi.json

Development API Documentation

URL: https://api-dev.learnille.com/docs
Swagger UI: Development environment API explorer
OpenAPI JSON: https://api-dev.learnille.com/docs/openapi.json

API Architecture

RESTful Design Principles

Resource-Based: APIs are organized around resources (users, courses, etc.)
HTTP Methods: Standard HTTP methods (GET, POST, PUT, DELETE)
Stateless: Each request contains all necessary information
HATEOAS: Hypermedia as the Engine of Application State

Authentication

All API endpoints require authentication using JWT (JSON Web Tokens).

Authorization: Bearer <jwt_token>

Token Acquisition

POST /auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "password"
}

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 3600
}

API Versioning

Current Version: v1
Version Header: Accept: application/vnd.learnille.v1+json
URL Versioning: /api/v1/
Deprecation Policy: 12 months notice for breaking changes

Core API Endpoints

User Management API

Get User Profile

GET /api/v1/users/{id}
Authorization: Bearer {token}

Update User Profile

PUT /api/v1/users/{id}
Authorization: Bearer {token}
Content-Type: application/json

{
  "first_name": "John",
  "last_name": "Doe",
  "bio": "Learning enthusiast"
}

List Users

GET /api/v1/users?role=student&limit=20&offset=0
Authorization: Bearer {token}

Course Management API

List Courses

GET /api/v1/courses?category=programming&level=beginner&limit=10

Get Course Details

GET /api/v1/courses/{id}

Create Course

POST /api/v1/courses
Authorization: Bearer {token}
Content-Type: application/json

{
  "title": "Introduction to React",
  "description": "Learn React fundamentals",
  "category_id": "uuid",
  "price": 49.99,
  "level": "beginner"
}

Update Course

PUT /api/v1/courses/{id}
Authorization: Bearer {token}
Content-Type: application/json

{
  "title": "Advanced React",
  "is_published": true
}

Delete Course

DELETE /api/v1/courses/{id}
Authorization: Bearer {token}

Enrollment API

Enroll in Course

POST /api/v1/enrollments
Authorization: Bearer {token}
Content-Type: application/json

{
  "course_id": "uuid"
}

Get Enrollment Progress

GET /api/v1/enrollments/{id}/progress
Authorization: Bearer {token}

Update Lesson Progress

PUT /api/v1/enrollments/{enrollment_id}/lessons/{lesson_id}/progress
Authorization: Bearer {token}
Content-Type: application/json

{
  "completed": true,
  "time_spent_minutes": 45
}

Payment API

Create Payment Intent

POST /api/v1/payments/intent
Authorization: Bearer {token}
Content-Type: application/json

{
  "amount": 49.99,
  "currency": "USD",
  "description": "Course enrollment"
}

Process Payment

POST /api/v1/payments/{id}/process
Authorization: Bearer {token}
Content-Type: application/json

{
  "payment_method_id": "pm_1234567890"
}

Get Payment History

GET /api/v1/payments?status=completed&limit=20
Authorization: Bearer {token}

Consultation API

List Available Consultations

GET /api/v1/consultations?category=programming&available=true

Book Consultation

POST /api/v1/consultations/{id}/book
Authorization: Bearer {token}
Content-Type: application/json

{
  "scheduled_at": "2024-01-15T14:00:00Z"
}

Get Consultation Details

GET /api/v1/consultations/{id}
Authorization: Bearer {token}

Search API

Search Courses

GET /api/v1/search/courses?q=react&category=programming&level=beginner

Search Users

GET /api/v1/search/users?q=john&role=instructor

Response Format

Success Response

{
  "success": true,
  "data": {
    "id": "uuid",
    "name": "Example",
    "created_at": "2024-01-01T00:00:00Z"
  },
  "meta": {
    "timestamp": "2024-01-01T00:00:00Z",
    "request_id": "req_123456"
  }
}

Error Response

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input data",
    "details": {
      "field": "email",
      "reason": "Invalid email format"
    }
  },
  "meta": {
    "timestamp": "2024-01-01T00:00:00Z",
    "request_id": "req_123456"
  }
}

Rate Limiting

Authenticated Requests: 1000 requests per hour
Unauthenticated Requests: 100 requests per hour
Search Requests: 50 requests per hour

Rate limit headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

Pagination

GET /api/v1/courses?limit=20&offset=0

Response:

{
  "success": true,
  "data": [...],
  "meta": {
    "pagination": {
      "total": 150,
      "limit": 20,
      "offset": 0,
      "has_more": true
    }
  }
}

Filtering and Sorting

Filtering

GET /api/v1/courses?category=programming&level=beginner&price_min=0&price_max=100

Sorting

GET /api/v1/courses?sort=created_at&order=desc
GET /api/v1/courses?sort=rating&order=desc

Webhooks

Payment Webhooks

POST /api/v1/webhooks/stripe
X-Signature: stripe_signature

{
  "type": "payment_intent.succeeded",
  "data": {
    "object": {
      "id": "pi_1234567890",
      "amount": 4999,
      "currency": "usd"
    }
  }
}

SDKs and Libraries

JavaScript SDK

import { LearnilleAPI } from 'learnille-sdk';

const client = new LearnilleAPI({
  apiKey: 'your-api-key',
  baseURL: 'https://api.learnille.com'
});

// Get courses
const courses = await client.courses.list({
  category: 'programming',
  limit: 10
});

Python SDK

from learnille_sdk import LearnilleAPI

client = LearnilleAPI(
    api_key='your-api-key',
    base_url='https://api.learnille.com'
)

# Get courses
courses = client.courses.list(category='programming', limit=10)

API Testing

Using cURL

# Get courses
curl -X GET "https://api.learnille.com/api/v1/courses" \
  -H "Authorization: Bearer your-jwt-token"

# Create course
curl -X POST "https://api.learnille.com/api/v1/courses" \
  -H "Authorization: Bearer your-jwt-token" \
  -H "Content-Type: application/json" \
  -d '{"title": "New Course", "description": "Course description"}'

Using Postman

Import OpenAPI specification
Set up environment variables for tokens
Use collection runner for automated testing

Error Codes

Code	Description
400	Bad Request - Invalid input
401	Unauthorized - Invalid/missing token
403	Forbidden - Insufficient permissions
404	Not Found - Resource doesn’t exist
409	Conflict - Resource already exists
422	Unprocessable Entity - Validation failed
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error - Server error

Support

For API support and questions:

Documentation: https://docs.learnille.com
Developer Forum: https://community.learnille.com
Email Support: api-support@learnille.com