REST API: Concepts and Basic Objects (Phase 1)

If you need any help in filling out this wiki page, please visit our ILIAS Community FAQ. And please complete the metadata information in the right column after having created the page.

1 Initial Problem

After a community-wide survey about the usage of webservices, features and ameriolations, the majority of responders wish ILIAS  had a REST API.  The platform has been using SOAP as its sole web service protocol (for both external and internal functionalities).  While ILIAS has been enjoying some of the benefits offered by SOAP, its singular implementation as the only web service option presents significant limitations and challenges in today's evolving web service landascape.  Hence, we propose to diversify our services by adding a REST API, to fit as many scenarios as possible.

1.1 Challenges With SOAP(And Offering SOAP As The Only Webservice)

1. Complexity and Heavyweight Structure: SOAP's reliance on comprehensive XML messages results in greater bandwidth consumption and slower processing times. This complexity hinders rapid development and integration, particularly in environments where efficiency and speed are paramount(such as mobile apps).
2. Barriers to Modern Web Development Practices: The rigid standards and structures of SOAP, including WSDL for defining services, create barriers to adopting modern, agile development methodologies.
3. Limited Flexibility and Scalability: The tightly coupled nature of SOAP services limits the platform's ability to adapt and scale efficiently. This has been presenting barriers  when  integrating  ILIAS in  third-party aplications.

1.2 The Case for a REST API: Technical and Strategic advantages

The proposal to introduce a RESTful API is not an attempt to replace or rectify SOAP's functionality within ILIAS but to complement it by offering an alternative that aligns with current web standards and developer expectations. The introduction of REST aims to mitigate the consequences of relying solely on SOAP by providing:

1. Simplicity and Flexibility: REST uses straightforward HTTP requests which also facilitates the understanding and implementation. It can handle multiple data formats which additionally offers flexibility in how data is consumed and presented. This is an advan
2. Lightweight: Unlike SOAP, which relies on XML for message formatting, REST can use lighter formats like JSON, reducing bandwidth usage and improving performance, particularly important for mobile and web applications.
3. Better Performance and Scalability: REST's stateless nature and cacheability lead to significantly improved response times and scalability, accommodating more users with fewer resources
4. Easier Integration and interoperability: The RESTful approach aligns with the architecture of the web, making it easier to integrate with a wide range of other tools and systems.
5. Browser-Friendliness
6. Standard Documentation

2 Conceptual Summary

Previous challenges in conceptualizing and implementing a RESTful API were related to ILIAS core design and the duplication of logic across different webservices. The function-based approach of the exisiting webservices like SOAP has led to difficulties in integrating a RESTful architecture without redundancy. To address these, we suggest to adopt a more resource-centric, or data-driven architectural model. The essence of this transition lies in abstracting the API's functionality to operate on resource entities rather than on specific procedural endpoints. In this way a REST API is divorced from the SOAP architecture and implemented as an independent webservice. Seeing that this is a long-term project, we propose that the implementations and integrations in phases.

In Phase 1 will focus on establishing a solid foundation for the REST API, prioritizing basic middlewares and creating endpoints for exposing  basic ILIAS components (starting with the most important components courses, users, and organisational units to already provide a useful interface after phase 1).

3 User Interface Modifications

No foreseeable UI modifications

4 Technical Information

{ The maintainer has to provide necessary technical information, e.g. dependencies on other ILIAS components, necessary modifications in general services/architecture, potential security or performance issues. }

5 Privacy

The API will only provide a layer on top of the existing ILIAS components. There is no direct manipulation of the user data

6 Security

The introduction of new endpoints inherently increases the surface area for potential attacks. Common concerns include endpoint vulnerabilities, such as injection attacks or unauthorized access, and the risks associated with token-based authentication if not properly implemented. To mitigate this we're prioritizing embedding security in the building blocks of the component:

• Employ rigorous input validation and sanitization to guard against injection and other common attacks.
• Implement robust authentication and authorization checks for each new endpoint. We plan to implement OAuth 2.0, a modern standard for secure authorization, which significantly reduces the risk associated with exposing new endpoints by ensuring that access is strictly controlled and monitored.
• Utilize HTTPS to secure data in transit, preventing man-in-the-middle attacks.
• Conduct thorough security testing and audits of the new endpoints to identify and rectify potential vulnerabilities before launch.

7 Contact

• Author of the Request: Abijuru, Jephte [Jephte]
• Maintainer: Minervis GmbH
  Abijuru, Jephte [Jephte]
• Implementation of the feature is done by: {The maintainer must add the name of the implementing developer.}

8 Funding

• If you are interest in funding this feature, please add your name and institution to this list.

• HHU / ILIAS.nrw Gruppe - 6.000,00 €

9 Discussion

10 Implementation

{ The maintainer has to give a description of the final implementation and add screenshots if possible. }

Test Cases

Test cases completed at {date} by {user}

• {Test case number linked to Testrail} : {test case title}

Privacy

Information in privacy.md of component: updated on {date} by {user} | no change required

Approval

Approved at {date} by {user}.