Feature Wiki

Information about planned and released features

Tabs

Activity I/O Validation Schemas (Phase 4)

1 Initial Problem

Activities describe user actions in ILIAS, for example, creating a course or listing its members. Each one holds its permission checks and logic in one place, so the web UI, the API, and workflows share the same code. An Activity either changes data (a Command) or reads data (a Query).

After Phase 3, the API could call Activities, but the ApiGateway ignored what they described about themselves:

  • No permission check before running: A request from a user who isn't allowed was only stopped inside the Activity, with no common "not allowed" response.
  • No input checks: Clients couldn't see what an endpoint expects. Each Activity validated its own input, which meant repeated code and inconsistent errors.
  • No output checks: Nothing made sure a response matches what the Activity promises.
  • Incomplete documentation: Developers had to read the Activity code to learn its inputs and outputs.

This is a long project. We split it into phases so that each phase is stable and useful on its own. Plans for later phases may change based on community feedback.

  • Phase 1: Webservices API base (REST, core structure, first Activity link, main API ideas)
  • Phase 2: Security and access control
  • Phase 3: Middleware, API documentation, and error handling
  • Phase 4: Authorization and input and output checks for Activities (this page)
  • Phase 5: SOAP webservice (add SOAP to the new ApiGateway component so that it can replace the current SOAP webservice over time)

2 Conceptual Summary

Phase 4 makes the ApiGateway use each Activity’s own description of who may run it, what it expects, and what it returns.

Authorization

  • The Activity still decides who may run it. A new AuthorizationMiddleware asks for that decision before the Activity runs, based on the user and the input.
  • If the user isn't allowed, the request is rejected with AuthorizationException (403).
  • Requests without a token are checked as a guest user. Only Activities that allow guests can run without login.

Input checks

  • Input is checked against the Activity's input description (required fields, types, rules), using the same form inputs as the web UI.
  • Wrong input is rejected with InputValidationException (422), with one error per field.

Output checks

  • Results are converted to simple types (text, numbers, true/false, lists) based on the output description.
  • A result that doesn't match returns ContractViolationException (500).

API documentation

  • The OpenAPI documentation is built from the input and output descriptions.
  • Swagger UI shows what each endpoint expects and returns, including login, token refresh, and ping.

3 User Interface Modifications

3.1 List of Affected Views

  • Swagger UI page: now shows what each endpoint expects and returns, including all Activity endpoints.
  • Webservices settings page: no changes in this phase.

3.2 User Interface Details

Swagger UI shows the OpenAPI documentation, which is built from the input and output descriptions of each Activity.

Swagger UI: Request & Response examples
Swagger UI: Object Activity as REST endpoint with URL parameter
Swagger UI: Example Activity as REST endpoint with all supported Input/Output elements

3.3 New User Interface Concepts

We use kitchen-sink elements, so there are no foreseeable new user-interface modifications.

3.4 Accessibility Implications

No foreseeable accessibility modifications.

4 Additional Information

4.1 Involved Authorities

4.2 Technical Aspects

4.2.1 Architectural Modifications

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

  • Every route now provides an input schema and an output schema:
    • Activity routes create them from the input and output descriptions of the Activity.
    • The built-in routes (login, token refresh, ping) define their own.
  • Input checks are done by a separate validator in the ApiGateway, not by each Activity.
  • Output conversion and checks are done by a separate result processor.
  • AuthorizationMiddleware is added to every Activity route by default.
  • InputValidationException and ContractViolationException report errors with one message per field, using the same error format as the other exceptions.

4.2.2 Dependencies

  • No new Composer dependencies.
  • Uses existing ILIAS parts: the Activities mechanism, the UI form inputs (for input checks), and the Data descriptions (for output checks).

4.2.3 Supported Input and Output Types

  • Input types: text, password, number, checkbox, select, multi-select, radio, date and time, and groups of these.
  • Output types: text, integer, number, true/false, date and time, null, lists, maps, and objects.

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:

  • Applying strict input validation and sanitization to prevent injection & related attacks.
  • Using prepared statements with parameterized queries (ALWAYS)
  • Enforcing strict authorization checks on each new endpoint.
  • Using HTTPS to secure data in transit.
  • Conducting thorough security testing and audits to identify and resolve vulnerabilities before launch.

4.5 Contact

This feature is developed by Minervis GmbH.

4.6 Funding

Funding needed: 26.800,00 €
Philipps-Universität Marburg - 4.200,00 € - done!
Universität Freiburg - 5.000,00 €

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 will be implemented by Hamouda, Ahmed [ahamouda].

6.1 Approval

Approved at {date} by {user}.

Last edited: 13. Nov 2026, 14:59, Hamouda, Ahmed [ahamouda]