Feature Wiki

Information about planned and released features

Tabs

REST API: Middlewares, Documentation and Error Handling (Phase 3)

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 ApiGateway component 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 off
    • RequestLoggingMiddleware: logs each request and response
    • RequestRateLimitingMiddleware: limits how many requests a client can make
    • JsonContentNegotiationMiddleware: checks that the client accepts JSON responses
    • JsonBodyParserMiddleware: reads the JSON request body
    • RequestParameterMiddleware: puts body and query parameters into one list
    • TransportSecurityMiddleware, BrowserSecurityMiddleware: add security headers
    • CorsMiddleware: 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.
Webservice Rate Limiting control
  • 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.
Swagger UI
Swagger UI: Response Examples
Swagger UI: Response Schemas
Swagger UI: "Try it out" feature

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 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.

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]