ILD Aggregation API Documentation

The ILD Aggregation service provides endpoints for managing statistics, learning trajectory objects (LTO), meta categories, changelog, and bug tracking. The API is divided into three main sections: Public, Private, and Admin endpoints.

Public Endpoints

These endpoints are accessible without authentication.

Meta Categories

Get All Meta Categories

  • Endpoint: GET /metacategory
  • Description: Retrieves all meta categories sorted by title
  • Response: json [ { "_id": "string", "title": "string", "description": "string", "parent": "string | null", "path": "string" } ]
  • Status Codes:
  • 200: Success
  • 500: Internal Server Error

Statistics

Get Public Team Statistics

  • Endpoint: GET /statistics/team/:teamId/last
  • Description: Retrieves public statistics for a specific team
  • Parameters:
  • teamId (path): Team identifier
  • Response: json { "statistics": { "curriculum": "number", "method": "number", "learningDesign": "number", "survey": "number" }, "content": { "curriculum": [], "method": [], "learningDesign": [], "survey": [] } }
  • Status Codes:
  • 200: Success
  • 500: Internal Server Error

Get Public User Statistics

  • Endpoint: GET /statistics/user/:userId/last
  • Description: Retrieves public statistics for a specific user
  • Parameters:
  • userId (path): User identifier
  • Response: Same as team statistics
  • Status Codes:
  • 200: Success
  • 500: Internal Server Error

Get Public OER Statistics

  • Endpoint: GET /statistics/oer/last
  • Description: Retrieves public statistics for OER
  • Response: Same as team statistics
  • Status Codes:
  • 200: Success
  • 500: Internal Server Error

Learning Trajectory Objects (LTO)

Team LTO

Get Public Team LTO
  • Endpoint: GET /lto/team/:teamId
  • Description: Retrieves public learning trajectory object for a team
  • Parameters:
  • teamId (path): Team identifier
  • Response: LTO object with team-specific data
  • Status Codes:
  • 200: Success
  • 404: Team not found
  • 500: Internal Server Error
Get Team Force Tags
  • Endpoint: GET /lto/team/:teamId/forcetags
  • Description: Retrieves force tags for team visualization
  • Parameters:
  • teamId (path): Team identifier
  • Response: Array of force tags
  • Status Codes:
  • 200: Success
  • 404: Team not found
  • 500: Internal Server Error
Get Team Force Increment
  • Endpoint: GET /lto/team/:teamId/forceincrement
  • Description: Retrieves force increment data for team visualization
  • Parameters:
  • teamId (path): Team identifier
  • Response: Force increment data object
  • Status Codes:
  • 200: Success
  • 404: Team not found
  • 500: Internal Server Error
Get Team Force Graph
  • Endpoint: GET /lto/team/:teamId/force
  • Description: Retrieves force graph data for team visualization
  • Parameters:
  • teamId (path): Team identifier
  • Response: Force graph data object
  • Status Codes:
  • 200: Success
  • 404: Team not found
  • 500: Internal Server Error

User LTO

  • GET /lto/user/:userId - Get public LTO for a user
  • GET /lto/user/:userId/forcetags - Get force tags for a user
  • GET /lto/user/:userId/forceincrement - Get force increment data for a user
  • GET /lto/user/:userId/force - Get force graph data for a user

OER LTO

  • GET /lto/oer - Get public LTO for OER
  • GET /lto/oer/forcetags - Get force tags for OER
  • GET /lto/oer/forceincrement - Get force increment data for OER
  • GET /lto/oer/force - Get force graph data for OER

Private Endpoints

These endpoints require authentication and appropriate role permissions.

Statistics

Get Team Statistics

  • Endpoint: GET /statistics/team/:teamId
  • Description: Retrieves detailed statistics for a team
  • Authentication: Required (Team role: ADMIN, GUEST, or MEMBER)
  • Parameters:
  • teamId (path): Team identifier
  • Response: json { "curriculum": "number", "method": "number", "methodCategory": "number", "learningDesign": "number", "surveys": "number", "storage": "string", "metaCategory": "number", "releaseNotes": "number", "bugs": "number" }
  • Status Codes:
  • 200: Success
  • 401: Unauthorized
  • 403: Forbidden
  • 500: Internal Server Error

Meta Categories

Create Meta Category

  • Endpoint: POST /metacategory
  • Description: Creates a new meta category
  • Authentication: Required (Admin)
  • Request Body: json { "title": "string", "description": "string", "parent": "string | null" }
  • Response: json { "_id": "string", "title": "string", "description": "string", "parent": "string | null", "path": "string" }
  • Status Codes:
  • 201: Created
  • 400: Bad Request
  • 401: Unauthorized
  • 403: Forbidden
  • 404: Parent category not found
  • 500: Internal Server Error

Get Meta Category Tree

  • Endpoint: GET /metacategory/tree
  • Description: Retrieves meta categories in a tree structure
  • Response: json [ { "_id": "string", "title": "string", "description": "string", "parent": "string | null", "path": "string", "children": [] } ]
  • Status Codes:
  • 200: Success
  • 500: Internal Server Error

Update Meta Category

  • Endpoint: PUT /metacategory/:categoryId
  • Description: Updates an existing meta category
  • Authentication: Required (Admin)
  • Parameters:
  • categoryId (path): Category identifier
  • Request Body: json { "title": "string", "description": "string", "parent": "string | null" }
  • Response: Updated category object
  • Status Codes:
  • 200: Success
  • 400: Bad Request
  • 401: Unauthorized
  • 403: Forbidden
  • 404: Category not found
  • 500: Internal Server Error

Delete Meta Category

  • Endpoint: DELETE /metacategory/:categoryId
  • Description: Deletes a meta category and all its children
  • Authentication: Required (Admin)
  • Parameters:
  • categoryId (path): Category identifier
  • Status Codes:
  • 204: No Content
  • 401: Unauthorized
  • 403: Forbidden
  • 404: Category not found
  • 500: Internal Server Error

Changelog

Get Changelog

  • Endpoint: GET /changelog
  • Description: Retrieves all changelog entries
  • Authentication: Required
  • Response: Array of changelog entries
  • Status Codes:
  • 200: Success
  • 401: Unauthorized
  • 500: Internal Server Error

Create Release Note

  • Endpoint: POST /changelog
  • Description: Creates a new release note
  • Authentication: Required (Admin)
  • Request Body: json { "version": "string", "title": "string", "description": "string", "date": "string" }
  • Response: Created release note object
  • Status Codes:
  • 201: Created
  • 400: Bad Request
  • 401: Unauthorized
  • 403: Forbidden
  • 500: Internal Server Error

Bug Tracking

Get Bugs

  • Endpoint: GET /bug
  • Description: Retrieves all bug reports
  • Authentication: Required (Admin)
  • Response: Array of bug reports
  • Status Codes:
  • 200: Success
  • 401: Unauthorized
  • 403: Forbidden
  • 500: Internal Server Error

Create Bug Report

  • Endpoint: POST /bug
  • Description: Creates a new bug report
  • Authentication: Required
  • Request Body: json { "title": "string", "description": "string", "severity": "string", "status": "string" }
  • Response: Created bug report object
  • Status Codes:
  • 201: Created
  • 400: Bad Request
  • 401: Unauthorized
  • 500: Internal Server Error

Admin Endpoints

These endpoints are specifically for administrative purposes.

Statistics

Get Admin Team Statistics

  • Endpoint: GET /statistics/team/:teamId
  • Description: Retrieves team statistics (admin only)
  • Authentication: Required (Admin)
  • Parameters:
  • teamId (path): Team identifier
  • Response: Same as team statistics
  • Status Codes:
  • 200: Success
  • 401: Unauthorized
  • 403: Forbidden
  • 500: Internal Server Error

Get Admin User Statistics

  • Endpoint: GET /statistics/user/:userId
  • Description: Retrieves user statistics (admin only)
  • Authentication: Required (Admin)
  • Parameters:
  • userId (path): User identifier
  • Response: Same as team statistics
  • Status Codes:
  • 200: Success
  • 401: Unauthorized
  • 403: Forbidden
  • 500: Internal Server Error

Error Responses

All endpoints may return the following error responses:

400 Bad Request

{
  "error": "string",
  "message": "string"
}

401 Unauthorized

{
  "error": "Unauthorized",
  "message": "Authentication required"
}

403 Forbidden

{
  "error": "Forbidden",
  "message": "Insufficient permissions"
}

404 Not Found

{
  "error": "Not Found",
  "message": "Resource not found"
}

500 Internal Server Error

{
  "error": "Internal Server Error",
  "message": "An unexpected error occurred"
}