Feature Wiki
Tabs
REST API: Middlewares, Documentation and Error Handling (Phase 3)
Page Overview
[Hide]- 1 Initial Problem
- 2 Conceptual Summary
- 3 User Interface Modifications
- 4 Additional Information
- 4.1 Involved Authorities
- 4.2 Technical Aspects
- 4.2.1 Existing Dependencies
- 4.2.2 Implementation Details
- 4.3 Privacy
- 4.3.1 Rate Limiting
- 4.4 Security
- 4.5 Contact
- 4.6 Funding
- 5 Discussion
- 6 Implementation
- 6.1 Description and Screenshots
- 6.2 Test Cases
- 6.3 Privacy
- 6.4 Approval
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 foundational REST API work (Phases 1 & 2), this phase focuses on abstracting the core business logic and API definitions from the underlying communication protocols.
The primary goals for Phase 3 are:
- Middlewares: Decouple cross-cutting concerns (like rate-limiting, content negotiation, and request validation) from the core API logic by introducing a formal PSR-15 middleware pipeline. This will improve code clarity and simplify maintenance.
- OpenAPI Documentation: Enable automatic documentation (viewable through Swagger). The OpenAPI specification will serve as a formal 'contract' for our API, providing a machine-readable definition of its capabilities, expected inputs, and guaranteed outputs.
- Error Handling: Improve error handling by integrating more deeply with ILIAS's native exception system, ensuring errors are reported in a clear, consistent, and predictable way.
1 Initial Problem
This phase is a build-up on previous progress, offering a more durable, maintainable & controlled API lifecycle.
- Protocol-specific middlewares are added at the edge of the system to handle HTTP-related tasks such as content negotiation and CORS.
- Automatic API documentation is generated in OpenAPI format and viewable using Swagger, making the available endpoints clear, consistent, and easy to understand for developers.
- Error handling is also improved and more closely aligned with ILIAS’s native exception system, ensuring that errors are reported in a clear, consistent, and predictable way, leading to smoother operation and easier debugging.
2 Conceptual Summary
This phase is a build-up on previous progress, offering a more durable, maintainable & controlled API lifecycle.
Protocol-specific middlewares are added at the edge of the system to handle HTTP-related tasks such as content negotiation and CORS.
Automatic API documentation is generated in OpenAPI format and viewable using Swagger, making the available endpoints clear, consistent, and easy to understand for developers.
Error handling is also improved and more closely aligned with ILIAS’s native exception system, ensuring that errors are reported in a clear, consistent, and predictable way, leading to smoother operation and easier debugging.
This project is an ongoing project, but phases have been split to ensure stability & new feature values for each delivered phase. Future phase details are subject to change based on community feedback or updates in planning.
- Phase 1 was about the Webservices API foundation, focusing on REST, delivering the core infrastructure, initial Activity integration, and key feature API concept definitions.
- Phase 2 focused on integrating security and access controls.
- Phase 3: Swagger & Middlewares is focusing on automatic documentation & improving how webservices behave, communicate, and report problems.
- Phase 4: Activity I/O Validation Schemas will focus on the automatic generation of OpenAPI documentation for activities that are discovered dynamically.
- Phase 5: SOAP Webservice Integration will focus on stabilization and current SOAP implementation clean-up based on feedback.
3 User Interface Modifications
3.1 List of Affected Views
- No foreseeable view modifications.
3.2 User Interface Details
No foreseeable UI modifications.
3.3 New User Interface Concepts
A new Rate Limiting section will be added to the Webservices general configuration page in the settings page in the admin dashboard to control how rate limiting middleware works.
3.4 Accessibility Implications
No foreseeable accessibility modifications.
4 Additional Information
4.1 Involved Authorities
- Authority to Sign off on Conceptual Changes: Hamouda, Ahmed [ahamouda]
- Authority to Sign off Code Changes: Hamouda, Ahmed [ahamouda]
- Authority to Curate Test Cases: Karki, Sagun [sagun]
- Assignee for Security Reports: Karki, Sagun [sagun] Assignee for Security Issues: Karki, Sagun [sagun]
4.2 Technical Aspects
4.2.1 Existing Dependencies
- Requires the following third-party libraries managed via Composer:
- `psr/log` For the logger interface.
4.2.2 Implementation Details
- OpenAPI/Swagger: The OpenAPI specification will be generated by a dedicated sub-module. Swagger will be used to view the generated
openapi.jsonschema.- Note that this will be handled without adding a new Composer dependency for Swagger itself.
- Middlewares introduced:
- Request throttling
RateLimitingMiddleware - Request validation (headers, body)
CorsMiddleware,JsonBodyParserMiddleware,AcceptJsonMiddlewareInternal.
- Request throttling
- Exceptions introduced:
MissingTokenException,InvalidTokenException,RateLimitExceededException,RequestLoggingMiddleware,InvalidJsonException,NotAcceptableException.
4.3 Privacy
The API will only provide a layer on top of the existing ILIAS components. There is no direct manipulation of the user data.
4.3.1 Rate Limiting
BUT, to apply rate limiting, some data will be collected to track visits to each endpoint and block abuse. A strict rule of "no raw data stored" will be applied during development and maintenance.
The following data will be collected in the form of a unique fingerprint for each user in salted hash value-form.
- ip address
- endpoint method
- endpoint uri
- user_id (if exists, otherwise null)
- Request timestamps
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. Even with new middlewares to check incoming input, they are not a replacement for proper input/output sanitization & validation Activity/Route.
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.
- For funding offers: Günther, Andre [ILIASBase].
- For technical inquiries: Hamouda, Ahmed [ahamouda].
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 in giving funding for this feature, please get in 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}
- {Test case number linked to Testrail} : {test case title}
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}.
Last edited: 16. Feb 2026, 16:29, Hamouda, Ahmed [ahamouda]