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.3 Privacy
- 4.3.1 Rate Limiting
- 4.4 Security
- 4.5 Contact
- 4.6 Funding
- 5 Discussion
- 6 Implementation
- 6.1 Approval
1 Initial Problem
Phase 2 made the REST API secure, but three things were still missing:
- Shared request handling: The only middleware was the login check. Nothing handled what every request needs, like rate limits, CORS, security headers, or checking that the request is valid JSON.
- API documentation: There was no documentation of the endpoints. Developers couldn’t easily see which endpoints exist, what to send, and what they get back.
- Clear errors: There were only two general error types (authentication and authorization). Clients couldn’t tell what exactly went wrong, for example a missing token, an invalid token, or too many requests.
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 (this page)
- Phase 4: Input and output checks for Activities (OpenAPI documentation created automatically for all Activities)
- Phase 5: SOAP webservice (add SOAP to the new
ApiGatewaycomponent so that it can replace the current SOAP webservice over time)
2 Conceptual Summary
Phase 3 adds three things to the ApiGateway component:
Middlewares
- Every request passes through a chain of PSR-15 middlewares before and after the endpoint code runs. This keeps these tasks out of the endpoint code.
- New middlewares:
ApiServiceStatusMiddleware: blocks requests when the webservice is turned offRequestLoggingMiddleware: logs each request and responseRequestRateLimitingMiddleware: limits how many requests a client can makeJsonContentNegotiationMiddleware: checks that the client accepts JSON responsesJsonBodyParserMiddleware: reads the JSON request bodyRequestParameterMiddleware: puts body and query parameters into one listTransportSecurityMiddleware, BrowserSecurityMiddleware: add security headersCorsMiddleware: handles requests from other domains
- Developers can add their own middlewares to single routes.
API documentation
- An OpenAPI file is created automatically. It describes every endpoint: what it expects and what it returns.
- The file can be viewed and tried out in Swagger UI.
- No new Composer dependency is needed for Swagger.
Error handling
- New, specific error types:
MissingTokenException,InvalidTokenException,InvalidCredentialsException,InvalidJsonException,MissingJsonPayloadException,NotAcceptableException,TooManyRequestsException. - Every error is returned with a matching HTTP status code. Unknown errors return 500.
- Errors can be logged, with or without full details.
3 User Interface Modifications
3.1 List of Affected Views
- The Webservices settings page (Administration > System Settings and Maintenance > Webservices), which has new settings on the REST tab
- The new Swagger UI page
3.2 User Interface Details
- The REST tab of the Webservices settings page gets two new settings:
- Rate limit: how many requests a client can make per minute. If it’s left empty, a default value is used.
- API documentation: turns the Swagger UI page on or off.

- A new Swagger UI page lists all Activities in ILIAS and the default endpoints. For each endpoint, it shows:
- response examples
- response schemas
- a “Try it out” button to send a test request
- When the API documentation is turned on, anyone can open the Swagger UI page. Admins can always open it.




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
- 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.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.
Request logging stores only the method, path, status code, runtime, and a request ID. No IP address or user data is logged.
4.3.1 Rate Limiting
To limit requests, the system has to recognize each client and count its requests. For this, it stores:
- A client fingerprint made from the IP address and the User-Agent (the name of the browser or app). The fingerprint is a secure hash, so the IP address and User-Agent are never stored in readable form.
- The endpoint that was called (HTTP method and path).
- The number and time of requests within the current time window.
No user ID or other user data is stored.
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 needed: 28.000,00 €
5.000,00 € - HSBI
5.000,00 € - HHU Düsseldorf / ILIAS.nrw Gruppe
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 Approval
Approved at {date} by {user}.
Last edited: 13. Nov 2026, 14:13, Hamouda, Ahmed [ahamouda]