soap Enterprise

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​

Prerequisites​

• For the Admin API tabs, set the Dashboard address and gateway group, then enter a Dashboard token:

  export API7_ADMIN_URL="https://localhost:7443"
  export API7_GATEWAY_GROUP_ID="default"
  printf "Dashboard token: "
  read -rs API7_ADMIN_KEY && export API7_ADMIN_KEY && echo
  

  The -k flag in these examples accepts the local Dashboard's self-signed certificate. Remove it when using a certificate trusted by the client.

• For the ADC tabs, select the api7ee backend and configure the corresponding Dashboard address, token, and gateway group.

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.

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

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

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

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

docker exec "$GATEWAY_CONTAINER" apisix reload

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

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

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

Invoke a SOAP Operation​

The following example demonstrates how to map POST /SayHello to the SayHello operation in the WSDL document.

Create the route:

curl -k "${API7_ADMIN_URL}/apisix/admin/services/soap-service?gateway_group_id=${API7_GATEWAY_GROUP_ID}" -X PUT \
  -H "X-API-KEY: ${API7_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "soap-service"
  }'

curl -k "${API7_ADMIN_URL}/apisix/admin/routes/soap-hello?gateway_group_id=${API7_GATEWAY_GROUP_ID}" -X PUT \
  -H "X-API-KEY: ${API7_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "soap-hello",
    "service_id": "soap-service",
    "paths": ["/SayHello"],
    "methods": ["POST"],
    "plugins": {
      "soap": {
        "wsdl_url": "https://apps.learnwebservices.com/services/hello?wsdl"
      }
    }
  }'

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
    upstream:
      type: roundrobin
      nodes:
        - host: httpbin.org
          port: 80
          weight: 1

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

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

apiVersion: v1
kind: Service
metadata:
  name: httpbin-external-domain
  namespace: aic
spec:
  type: ExternalName
  externalName: httpbin.org
  ports:
    - name: http
      port: 80
      protocol: TCP
---
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
      backendRefs:
        - name: httpbin-external-domain
          port: 80
---
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

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"

kubectl apply -f soap-ic.yaml

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

The ADC and Gateway API tabs include a conventional backend. When the plugin handles the request itself, the backend is not contacted. Verify the plugin-specific result below; a backend response alone does not confirm that the plugin ran.

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!"