Skip to main content

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​

Development API Documentation​

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​

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

Support​

For API support and questions: