Skip to main content
Sakai LMS provides multiple API layers for accessing learning management system functionality programmatically. The API architecture consists of modern REST endpoints and a flexible entity broker system.

​
API Architecture

Sakai’s API is built on several complementary layers:

​
1. Modern REST API (WebAPI)

The WebAPI module provides modern Spring-based REST controllers located in webapi/src/main/java/org/sakaiproject/webapi/controllers/. These endpoints follow RESTful conventions and return JSON responses. Base Path: /api/ Key Controllers:
  • LoginController - Authentication and session management
  • UserController - User information and roles
  • SitesController - Site/course information
  • DashboardController - Dashboard data
  • CalendarController - Calendar events
  • AnnouncementsController - Announcements
  • GradesController - Gradebook access
  • ForumsController - Forum discussions
  • TasksController - Task management
  • NotificationsController - User notifications
Example Controller Implementation: 
// webapi/src/main/java/org/sakaiproject/webapi/controllers/UserController.java:35
@GetMapping("/user/roles")
public ResponseEntity<Map<String, Boolean>> checkSuperUser() {
    return ResponseEntity.ok()
        .contentType(MediaType.APPLICATION_JSON)
        .body(Map.of("isSuperUser", securityService.isSuperUser()));
}

​
2. Entity Broker System

The Entity Broker provides a flexible, capability-based system for exposing entities via REST APIs. Located in the entitybroker/ module, it allows tools to register entity providers that automatically expose CRUD operations. Base Path: /direct/ Key Features:
  • Auto-registration of entity providers
  • CRUD operations (Create, Read, Update, Delete)
  • Custom actions on entities
  • Multiple output formats (JSON, XML, HTML)
  • Search and filtering capabilities
  • Batch operations
Entity Provider Example: 
public interface EntityProvider {
    /**
     * Controls the globally unique prefix for the entities
     * handled by this provider.
     * Example: "annc" for announcements, "eval" for evaluations
     */
    public String getEntityPrefix();
}
URL Pattern: /direct/{prefix}/{id}/{action}.{format} Examples:
  • /direct/assignment/123.json - Get assignment with ID 123 as JSON
  • /direct/site/site123/pages.xml - Get pages for site as XML
  • /direct/user/current.json - Get current user as JSON

​
3. Java Kernel Services

The Kernel provides core services that both APIs use internally: Session Management (SessionManager): 
// kernel/api/src/main/java/org/sakaiproject/tool/api/SessionManager.java:84
Session getCurrentSession();
String getCurrentSessionUserId();
Session startSession();
User Services (UserDirectoryService):
  • User authentication and management
  • User profile access
  • Preferences management
Site Services (SiteService):
  • Course/project site management
  • Site membership and permissions
  • Tool configuration within sites
Content Hosting (ContentHostingService):
  • File upload and storage
  • Resource management
  • Collections and folders
Authorization (AuthzGroupService, SecurityService):
  • Permission checking
  • Role management
  • Security assertions

​
API Request Flow

All API requests must include a valid Sakai session. The session is typically established via the /api/login endpoint and maintained using session cookies.
  1. Authentication: Client authenticates via /api/login
  2. Session Creation: Server creates session and returns session ID
  3. Session Cookie: Client includes JSESSIONID cookie in subsequent requests
  4. Request Processing: API controllers validate session and process request
  5. Response: Server returns JSON/XML response

​
Available Endpoints

​
Sites and Courses

// webapi/src/main/java/org/sakaiproject/webapi/controllers/SitesController.java:58
@GetMapping(value = "/users/{userId}/sites", produces = MediaType.APPLICATION_JSON_VALUE)
public Map<String, List<Map<String, Object>>> getSites(
    @PathVariable String userId,
    @RequestParam Optional<Boolean> pinned
)
Returns:
  • List of user’s sites/courses
  • Site tools and configuration
  • Pinned sites
  • Site notifications

​
User Information

Access user profiles, roles, and permissions:
  • /api/user/roles - Check user roles
  • /direct/user/{userId}.json - Get user profile

​
Calendar and Events

Manage calendar events and schedules:
  • /api/calendar/* - Calendar operations
  • /direct/calendar/* - Calendar entity access

​
Gradebook

Access grades and assignments:
  • /api/grades/* - Gradebook data
  • /direct/gradebook/* - Gradebook entities

​
Data Formats

Both API layers support multiple data formats: JSON (Default): 
GET /api/user/roles
GET /direct/site/123.json
XML: 
GET /direct/site/123.xml
Format Constants: 
// entitybroker/api/src/java/org/sakaiproject/entitybroker/entityprovider/extension/Formats.java
public static final String JSON = "json";
public static final String XML = "xml";
public static final String HTML = "html";
public static final String ATOM = "atom";
public static final String RSS = "rss";

​
Error Handling

APIs use standard HTTP status codes:
  • 200 OK - Successful request
  • 201 Created - Resource created successfully
  • 400 Bad Request - Invalid request parameters
  • 401 Unauthorized - Missing or invalid authentication
  • 403 Forbidden - Insufficient permissions
  • 404 Not Found - Resource not found
  • 500 Internal Server Error - Server error
Example Error Handler: 
// webapi/src/main/java/org/sakaiproject/webapi/controllers/AbstractSakaiApiController.java:56
Session checkSakaiSession() {
    try {
        Session session = sessionManager.getCurrentSession();
        if (StringUtils.isBlank(session.getUserId())) {
            log.error("Sakai user session is invalid");
            throw new MissingSessionException();
        }
        return session;
    } catch (IllegalStateException e) {
        log.error("Could not retrieve the sakai session");
        throw new MissingSessionException(e.getCause());
    }
}

​
Security Considerations

Important: All API endpoints respect Sakai’s security model. Users can only access resources they have permission to view or modify.
  • Session-based authentication required
  • Permission checks on all operations
  • Site membership validation
  • Resource-level access control
  • Audit logging of API access

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us