Feature Wiki

Information about planned and released features

Tabs

SOAP Webservice Integration (Phase 5)

1 Summary

Phases 1 to 4 built a REST API on top of ILIAS Activities, with authentication, middleware, documentation, and schema validation. Phase 5 is the last planned phase. It adds SOAP to the same `ApiGateway` component, so that both protocols use the same Activities and the same security.

The goals of Phase 5 are:

  • SOAP for every Activity: Each Activity that works over REST will also work over SOAP, without any change to the Activity.
  • SOAP behaves like REST: the same security, limits, and logging apply.
  • Admin control and documentation: Administrators will switch SOAP on or off in the same place as REST. Clients get a generated service description (WSDL).

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
  • Phase 5: SOAP webservice (add SOAP to the new ApiGateway component so that it can replace the current SOAP webservice over time) (this page)

2 Problem Statement

Phase 1 added REST because SOAP, as the only protocol, was heavy and hard to integrate. REST was meant to complement SOAP, not replace it. Many existing integrations and enterprise tools still need SOAP.

The old SOAP server (public/soap/server.php) does not benefit from the work of Phases 2 to 4:

  • It repeats business logic that Activities already provide.
  • It does not use the token login, permission checks, rate limiting, or logging of the `ApiGateway`.
  • Its inputs and outputs are not described by the Activity schemas, so documentation and behavior can differ.
  • It is configured separately from the other webservices.

As a result, ILIAS keeps two webservice stacks that behave differently. New Activities are only available over REST.

3 Concept

Phase 5 adds SOAP next to REST in the ApiGateway component. Both webservices run the same Activities.

Endpoint

  • SOAP 1.1 requests go to /soap/v2.
  • Each SOAP operation is named after its REST route; for example /apigateway/helloworld becomes apigatewayHelloworld.
  • For each request, the endpoint:
    • checks the login and the permissions
    • checks the input against the Phase 4 schemas
    • runs the Activity
    • checks the result against the Phase 4 schemas
  • Errors are returned as soap:Fault.

Login

  • The SOAP webservice offers its own login and token refresh operations. They issue the same tokens as the REST login, so a SOAP-only client does not need REST.
  • A token from either webservice works with both.

XML conversion

  • Requests and responses use SOAP 1.1 in document/literal style.
  • The XML request body is converted into Activity input, and the Activity result is converted back into XML. Both directions follow the Phase 4 input and output schemas, which also define the types in the WSDL.
  • Conversion rules:
    • Objects become an element with one child element per field.
    • Lists become a wrapper element with one item child element per entry.
    • Maps become a wrapper element with one entry child element per key, each holding a key and a value.
    • True/false, integers, numbers, and date and time use the standard XML Schema types (xsd:boolean, xsd:int, xsd:decimal, xsd:dateTime).
    • Null values are sent as an empty element marked xsi:nil="true". An empty element without that mark is an empty string.

Compatibility

  • REST clients, the old SOAP server, and existing data do not change.
  • The old and new SOAP endpoints run side by side.
  • The v2 in the URL only separates the new endpoint from the old one. It will be removed when the old SOAP server is retired.

4 User Interface Modifications

4.1 List of Affected Views

Administration > System Settings and Maintenance > Webservices > SOAP tab. The tab currently opens the old SOAP settings. Phase 5 replaces it with a settings form for the new SOAP webservice.

The old SOAP settings stay in Administration > Authentication and Registration > SOAP and keep controlling the old SOAP server. The new SOAP tab shows a link to them until the old server is retired.

4.2 User Interface Details

The SOAP tab gets the same form as the REST tab:

  • Activate Webservice: SOAP on or off. Default: off.
  • Activate WSDL: Guests can open the WSDL at `/soap/v2?wsdl`. Default: off.
  • Rate Limit: Maximum requests per minute. Planned default: 300.

4.3 New User Interface Concepts

None.

4.4 Technical Aspects

  • Each webservice owns its routes. Only Activities are shared.
  • The WSDL is generated from the Activity schemas, so documentation and behavior match.
  • A new public entry point at soap/v2. Its .htaccess disables the /soap/v2 to /soap/v2/ redirect, which most SOAP clients do not follow.
  • The new endpoint is /soap/v2, without /index.php.
  • Only Bearer tokens are accepted. The session-based login of the old SOAP server is not supported.
  • No new Composer dependency is needed. Only the ApiGateway component changes.

5 Non-Functional Implications

5.1 Security

A new endpoint and a new input format (XML) change the attack surface. The parser rejects documents with a DTD and does not load external resources (XXE). A request size limit is added on top of rate limiting. Each operation uses the permission checks of its Activity, so SOAP can never do more than REST. A written security concept will be delivered with the feature and needs Jour Fixe approval before merge.

5.2 Privacy

Rate limiting works as described in Phase 3. It stores a client fingerprint made from the IP address and the User-Agent (a secured hash, never readable), the endpoint that was called, and the number and time of requests. No user ID is stored.

5.3 Accessibility Implications

None foreseen. The form uses standard ILIAS UI components.

6 Process Information

6.1 Involved Authorities

6.2 Contact

This feature is developed by Minervis GmbH.

6.3 Funding

Funding needed: 21.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'.

7 Discussion

8 Implementation

The feature will be implemented by Hamouda, Ahmed [ahamouda].

8.1 Description and Screenshots

{ Description of the final implementation and the changed behaviour in the related components. Please add screenshots to visualise the changes if possible. }

8.2 Test Cases

Test cases completed at {date} by {user}

  • {Test case number linked to Testrail} : {test case title}

8.3 Privacy

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

8.4 Approval

Approved at {date} by {user}.

Last edited: 13. Nov 2026, 15:30, Hamouda, Ahmed [ahamouda]