Activity I/O Validation Schemas (Phase 4)

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.

Building on the foundations laid in the previous phases, this fourth phase focuses on solidifying the integration between the ApiGateway component and the Activity mechanism in ILIAS. It leverages Activities' existing capabilities to automate and separate processes that are not directly related to business logic. This phase is considered the final step towards a complete and official ILIAS REST API webservice.

1 Initial Problem

In the current state of the REST API, there is no standardized way for clients to know what data should be submitted to an endpoint or what the structure of the response will be. Because these requirements are currently unknown to the system at a structural level, they cannot be communicated or enforced automatically.

This lack of standardization forces each Activity to manually implement its own validation and error handling.

Activities represent specific actions a user can perform in ILIAS, such as "Create a Course" or "Get Member List". They act as a central bridge that connects the REST API to the system's core logic. An Activity handles a complete process, including checking permissions and processing data, in a single place.

This makes them "universal," meaning the same logic can be used by the web interface, the API, or automated workflows. They usually either perform an action that changes the system (Commands) or simply fetch information (Queries). More details on the technical design can be found in the Activities README.

In Phase 4, the reliance on manual implementation within these Activities leads to several issues and significantly higher development effort:

2 Conceptual Summary

To address these problems, Phase 4 introduces a schema-driven approach to input and output validation. By enabling the ApiGateway to process the information provided by the getInputDescription() and getOutputDescription() methods of an Activity, we move from manual implementation to automated enforcement.

This transition dramatically reduces development effort and makes the interface significantly easier to use for both maintainers and consumers through the following automations:

3 3 User Interface Modifications

3.1 3.1 List of Affected Views

3.2 User Interface Details

3.3 New User Interface Concepts

3.4 Accessibility Implications

4 Additional Information

4.1 Involved Authorities

4.2 Technical Aspects

4.2.1 4.2.1 Architectural Modifications

The core of this phase is the introduction of a more formal contract between the ApiGateway and the Activities.

4.3 Privacy

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

4.4 Security

As in the previous phases, adding new endpoints inherently increases the attack surface, introducing risks such as injection attacks and unauthorized access.

To mitigate these, users should embed security into the component's building blocks by:

4.5 Contact

This feature is developed by Minervis GmbH.

4.6 Funding

Funding status and funding parties are listed in the block 'Status of Feature' in the right column of this page.

If you are interested to give funding for this feature, please get into contact with the person mentioned above as 'Contact'.

5 Discussion

6 Implementation

The feature has been implemented by Hamouda, Ahmed [ahamouda].

6.1 Description and Screenshots

{ Description of the final implementation and screenshots if possible. }

6.2 Test Cases

Test cases completed at {date} by {user}

6.3 Privacy

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

6.4 Approval

Approved at {date} by {user}.