SOAP WSDL Management API¶

• SOAP WSDL Management API
  • Configuration
    • Add Permissions for the SOAP WSDL Management API
  • Request Object Reference
  • API Routes
    • Get Enabled SOAP WSDLs
    • Add SOAP WSDLs (Merge + Runtime Reload)
    • Remove SOAP WSDLs (Runtime Reload)
  • Error Handling

This API provides a way to manage (list, add, and remove) enabled SOAP WSDL services for a specific server through REST, without regenerating directory.xml and without restarting the server.
It is implemented by WsdlRestHandler and performs a runtime SOAP WSDL reload after successful updates.

The work on this feature was implemented in #11067.

Configuration¶

SOAP WSDL Management API is a sub-module of Administration_REST_API. To use it, the global REST API must be enabled. Please see Administration_REST_API. There are no additional setup requirements for this sub-module.

Add Permissions for the SOAP WSDL Management API¶

To access this API, grant ACL permissions for the endpoint family:

<node class="container" name="security">
  <node class="container" name="acl">
    <node class="container" name="webservice">
      <!-- GET /admin/config/wsdls/{server-id} -->
      <node class="container" name="000200">
        <node class="resource" name="resource-instance">
          <node-attribute name="reference" value="ADMIN:GET:/admin/config/wsdls/.*"/>
          <node-attribute name="reftype" value="FALSE"/>
        </node>
        <node class="webServiceRights" name="rights">
          <node-attribute name="allow" value="true"/>
        </node>
        <node class="strings" name="subjects">
          <node-attribute name="values" value="restAdmin"/>
        </node>
      </node>
      <!-- PUT /admin/config/wsdls/{server-id} -->
      <node class="container" name="000201">
        <node class="resource" name="resource-instance">
          <node-attribute name="reference" value="ADMIN:PUT:/admin/config/wsdls/.*"/>
          <node-attribute name="reftype" value="FALSE"/>
        </node>
        <node class="webServiceRights" name="rights">
          <node-attribute name="allow" value="true"/>
        </node>
        <node class="strings" name="subjects">
          <node-attribute name="values" value="restAdmin"/>
        </node>
      </node>
      <!-- DELETE /admin/config/wsdls/{server-id} -->
      <node class="container" name="000202">
        <node class="resource" name="resource-instance">
          <node-attribute name="reference" value="ADMIN:DELETE:/admin/config/wsdls/.*"/>
          <node-attribute name="reftype" value="FALSE"/>
        </node>
        <node class="webServiceRights" name="rights">
          <node-attribute name="allow" value="true"/>
        </node>
        <node class="strings" name="subjects">
          <node-attribute name="values" value="restAdmin"/>
        </node>
      </node>
    </node>
  </node>
</node>

For the definition of admin-rest FWD user, see Administration_REST_API.

By setting these ACL entries, you allow:

Request Object Reference¶

The request body is a JSON object used by PUT and DELETE:

Notes:

• Duplicate identifiers are de-duplicated automatically.
• PUT merges incoming values with the existing enabled set.
• DELETE removes only the listed values from the existing enabled set.
• GET ignores request body and returns current state.

API Routes¶

The SOAP WSDL Management API has the following capabilities:

• Authentication: login/logout are provided by the main module. See Administration_REST_API.
• List enabled WSDLs: retrieve current enabled identifiers for a target server.
• Enable WSDLs: add one or more identifiers to the existing enabled set.
• Disable WSDLs: remove one or more identifiers from the existing enabled set.
• Runtime reload: on successful PUT/DELETE, runtime SOAP WSDL mappings are reloaded.

Get Enabled SOAP WSDLs¶

Retrieve enabled WSDL identifiers for a server by performing a GET request at /admin/config/wsdls/{server-id}.
Header must include a valid FwdSessionId token.

Show example - successful getShow example - successful get

GET /admin/config/wsdls/default HTTP/1.1
Host: localhost:8443
FwdSessionId: 0ea12c7b-9c76-4bdb-8e8e-450d93b3b065

{
  "wsdls": "CustomerService.wsdl,OrderService.wsdl" 
}

Show example - unknown serverShow example - unknown server

GET /admin/config/wsdls/unknown-server HTTP/1.1
Host: localhost:8443
FwdSessionId: 0ea12c7b-9c76-4bdb-8e8e-450d93b3b065

{
  "success": false,
  "error": "Unknown server id: unknown-server" 
}

Add SOAP WSDLs (Merge + Runtime Reload)¶

Add one or more SOAP WSDL identifiers by performing a PUT request at /admin/config/wsdls/{server-id}.
Header must include a valid FwdSessionId token.

• wsdls is required.
• Existing identifiers are preserved.
• New identifiers are merged and de-duplicated.

Show example - successful putShow example - successful put

PUT /admin/config/wsdls/default HTTP/1.1
Host: localhost:8443
FwdSessionId: 0ea12c7b-9c76-4bdb-8e8e-450d93b3b065
Content-Type: application/json

{
  "wsdls": "CustomerService.wsdl,OrderService.wsdl" 
}

{
  "success": true,
  "message": "SOAP WSDLs updated to: CustomerService.wsdl,OrderService.wsdl. Runtime SOAP WSDL mappings were reloaded." 
}

Show example - partial success (unknown wsdl ignored)Show example - partial success (unknown wsdl ignored)

PUT /admin/config/wsdls/default HTTP/1.1
Host: localhost:8443
FwdSessionId: 0ea12c7b-9c76-4bdb-8e8e-450d93b3b065
Content-Type: application/json

{
  "wsdls": "DoesNotExist.wsdl" 
}

{
  "success": true,
  "errors": [
    "Ignored SOAP WSDLs (not found): DoesNotExist.wsdl" 
  ]
}

Show example - failure (missing wsdls)Show example - failure (missing wsdls)

PUT /admin/config/wsdls/default HTTP/1.1
Host: localhost:8443
FwdSessionId: 0ea12c7b-9c76-4bdb-8e8e-450d93b3b065
Content-Type: application/json

{
  "other": "value" 
}

{
  "success": false,
  "errors": [
    "Missing required field: wsdls" 
  ]
}

Show example - failure (unknown server)Show example - failure (unknown server)

PUT /admin/config/wsdls/unknown-server HTTP/1.1
Host: localhost:8443
FwdSessionId: 0ea12c7b-9c76-4bdb-8e8e-450d93b3b065
Content-Type: application/json

{
  "wsdls": "CustomerService.wsdl" 
}

{
  "success": false,
  "errors": [
    "Unknown server id: unknown-server" 
  ]
}

Remove SOAP WSDLs (Runtime Reload)¶

Remove one or more SOAP WSDL identifiers by performing a DELETE request at /admin/config/wsdls/{server-id}.
Header must include a valid FwdSessionId token.

• wsdls is required.
• Only listed identifiers are removed.
• If all values are removed, the endpoint reports that all SOAP WSDLs are disabled.

Show example - successful delete (some remain)Show example - successful delete (some remain)

DELETE /admin/config/wsdls/default HTTP/1.1
Host: localhost:8443
FwdSessionId: 0ea12c7b-9c76-4bdb-8e8e-450d93b3b065
Content-Type: application/json

{
  "wsdls": "OrderService.wsdl" 
}

{
  "success": true,
  "message": "SOAP WSDLs updated to: CustomerService.wsdl. Runtime SOAP WSDL mappings were reloaded." 
}

Show example - successful delete (all removed)Show example - successful delete (all removed)

DELETE /admin/config/wsdls/default HTTP/1.1
Host: localhost:8443
FwdSessionId: 0ea12c7b-9c76-4bdb-8e8e-450d93b3b065
Content-Type: application/json

{
  "wsdls": "CustomerService.wsdl,OrderService.wsdl" 
}

{
  "success": true,
  "message": "All SOAP WSDLs have been disabled. Runtime SOAP WSDL mappings were reloaded." 
}

Error Handling¶

The API uses standard HTTP status codes: