soap

The soap plugin converts JSON requests into SOAP operations defined by a Web Services Description Language (WSDL) document. It also converts the SOAP response into JSON before returning it to the client.

The plugin delegates WSDL parsing and protocol conversion to soap-proxy, which must be reachable from every gateway instance.

Examples

The following workflow starts the SOAP proxy, configures its gateway endpoint, and invokes a public SOAP operation through API7 Gateway.

Set Up SOAP Proxy

Choose the setup that matches the gateway deployment.

Set GATEWAY_CONTAINER to the running API7 Gateway container. Create a dedicated network and connect the gateway to it:

export GATEWAY_CONTAINER=replace-with-gateway-container-name

docker network create gateway-soap-net
docker network connect gateway-soap-net "$GATEWAY_CONTAINER"

Start the SOAP proxy on the shared network with the image used by the current API7 Gateway chart:

docker run -d \
  --name soap-proxy \
  --network gateway-soap-net \
  api7/soap-proxy:1.0.0

Add the SOAP proxy endpoint to the persistent config.yaml used by the gateway deployment:

config.yaml

plugin_attr:
  soap:
    endpoint: http://soap-proxy:5000
    timeout: 3000

Reload the gateway after updating its configuration source:

docker exec "$GATEWAY_CONTAINER" apisix reload

Add the SOAP proxy sidecar and plugin attributes to the complete, source-controlled values file used by the gateway release:

values.yaml

soapProxy:
  enabled: true
  image:
    repository: api7/soap-proxy
    tag: 1.0.0
pluginAttrs:
  soap:
    endpoint: http://127.0.0.1:5000
    timeout: 3000

Set the release details, including the chart version already used by the deployment:

export GATEWAY_RELEASE=replace-with-gateway-release-name
export GATEWAY_NAMESPACE=replace-with-gateway-namespace
export GATEWAY_CHART_VERSION=replace-with-installed-chart-version

Apply the complete values file without changing the chart version:

helm upgrade "$GATEWAY_RELEASE" api7/gateway \
  --namespace "$GATEWAY_NAMESPACE" \
  --version "$GATEWAY_CHART_VERSION" \
  -f values.yaml

The sidecar shares the gateway Pod's network namespace, so the gateway reaches it at 127.0.0.1:5000.

Invoke a SOAP Operation

Create a route that maps POST /SayHello to the SayHello operation in the WSDL document:

curl "http://127.0.0.1:9180/apisix/admin/routes/soap-hello" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "uri": "/SayHello",
    "methods": ["POST"],
    "plugins": {
      "soap": {
        "wsdl_url": "https://apps.learnwebservices.com/services/hello?wsdl"
      }
    }
  }'

adc.yaml

services:
  - name: soap-service
    labels:
      docs-example: soap
    routes:
      - name: soap-hello
        uris:
          - /SayHello
        methods:
          - POST
        plugins:
          soap:
            wsdl_url: "https://apps.learnwebservices.com/services/hello?wsdl"

Preview changes owned by this example and confirm that the diff contains no unintended updates or deletions:

adc diff -f adc.yaml \
  --include-resource-type service \
  --label-selector docs-example=soap

Synchronize the reviewed service configuration:

adc sync -f adc.yaml \
  --include-resource-type service \
  --label-selector docs-example=soap

soap-ic.yaml

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  namespace: aic
  name: soap-hello
spec:
  parentRefs:
    - name: apisix
  rules:
    - matches:
        - path:
            type: Exact
            value: /SayHello
          method: POST
      filters:
        - type: ExtensionRef
          extensionRef:
            group: apisix.apache.org
            kind: PluginConfig
            name: soap-plugin-config
---
apiVersion: apisix.apache.org/v1alpha1
kind: PluginConfig
metadata:
  namespace: aic
  name: soap-plugin-config
spec:
  plugins:
    - name: soap
      config:
        wsdl_url: "https://apps.learnwebservices.com/services/hello?wsdl"

soap-ic.yaml

apiVersion: apisix.apache.org/v2
kind: ApisixRoute
metadata:
  namespace: aic
  name: soap-hello
spec:
  ingressClassName: apisix
  http:
    - name: soap-hello
      match:
        paths:
          - /SayHello
        methods:
          - POST
      plugins:
        - name: soap
          enable: true
          config:
            wsdl_url: "https://apps.learnwebservices.com/services/hello?wsdl"

Apply the configuration:

kubectl apply -f soap-ic.yaml

The request path identifies the WSDL operation, and wsdl_url identifies the service contract and upstream SOAP endpoint.

Send a JSON request to the route:

curl -i "http://127.0.0.1:9080/SayHello" \
  -H "Content-Type: application/json" \
  -d '{"Name": "John Doe"}'

API7 Gateway should return HTTP/1.1 200 OK with the following response body:

"Hello John Doe!"

soap Enterprise

Examples

Set Up SOAP Proxy

Invoke a SOAP Operation

soap