APIcast & SOAP

SaaS On-premises 2.0
This tutorial shows what changes you need to make to your SOAP envelope and NGINX and Lua files to successfully integrate with 3scale. More detailed instructions can be found on other support pages, as indicated, with these modifications for SOAP.

SOAP envelope

This example will illustrate the changes you need to make to the SOAP envelope. A call to the API backend is made with the following request:

curl -X POST -H "Content-Type: text/xml" -d @request.xml http://you-api.com/path

Where request.xml follows the SOAP v1.2 structure and looks like this:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
        <setAB xmlns="http://your-xml-ns/">
            <arg0 xmlns="">12</arg0>
            <arg1 xmlns="">23</arg1>

Put the elements necessary for integration with 3scale in the SOAP header. Here is an example of the modified SOAP envelope.

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"  xmlns:t="http://3scale.net/soap/" soap:mustUnderstand="false" >
        <setAB xmlns="http://your-xml-ns/">
            <arg0 xmlns="">12</arg0>
            <arg1 xmlns="">23</arg1>

The element t:ApiKey corresponds to the credentials that can be found on your Applications page, and t:method corresponds to the method defined in your SOAP body. This modified request is sent to the API gateway:

curl -X POST -H "Content-Type: text/xml" -d @request.xml http://your-nginx-instance:80

NGINX/Lua configuration

  1. Follow the instructions here for NGINX configuration. For the moment, ignore the "Download your API gateway configuration from 3scale" section – you'll come back to it later.
  2. As well as installing the Lua plugin as discussed in APIcast Self-Managed, you'll need to install an additional module named "Luaxml":
    sudo apt-get install luarocks
    sudo luarocks install luaxml
    To verify, you should see luaxml installed inside /usr/local/lib/luarocks/rocks. You can use the command luarocks show luaxml to print the luaxml version.
  3. Now get back to "Download your API gateway configuration from 3scale". After entering your private API host*, you'll map SOAP operations to 3scale metrics.
    SOAP Mapping
    Choose GET or POST as appropriate. In the Pattern box, choose the SOAP operation you want to manage, measure, or protect. Prefix the operation name with a "/". Choose the metric you want to measure against. After you update and test it, it may show errors. Proceed with the config download anyway.
  4. Prior to starting NGINX, as discussed in APIcast self-managed, you may need to make a few tweaks to your configuration.
  5. Modify the nginx_XXXXX.conf, following the instructions in section "Download your API gateway configuration from 3scale".
  6. Modify the file nginx_XXXXX.lua
    • Add this snippet to the start of the file before the service declaration.
      function extract_value(xmlpayload, val)
        return xmlpayload:find(val)[1]
    • Change the signature and this line of method extract_usage_xxxxx as shown here:
      function extract_usage_xxxxxxx(request, xmlpayload)
      local t = string.split(request," ")
      local method = t[1]
      local path = extract_value(xmlpayload, "t:method");
      Or comparing old with new:
    • In the if ngx.var.service_id == block toward the end of the file, insert and change params.user_key = parameters["user_key"] as shown:
      local xmlpayload = xml.eval(ngx.req.get_body_data())        
      params.user_key = extract_value(xmlpayload, "t:ApiKey")
      Comparing old vs. new:
      The API key will be taken from the SOAP XML as discussed below.
    • Also in the if ngx.var.service_id == block, add the path to your API: ngx.var.proxy_pass = "http://backend_www.your-api.com/path/to/your/api"
    • Also in the if ngx.var.service_id == block, change ngx.var.usage = extract_usage_xxxxxxxx(ngx.var.request)
      ngx.var.usage = extract_usage_xxxxxxxx(ngx.var.request, xmlpayload)
  7. Now when you copy the NGINX config and Lua to /usr/local/openresty/nginx/conf/ as discussed in APIcast configuration, and you start the server, it should be ready to accept SOAP requests.
  8. Assuming NGINX is running on localhost:80, you can test your API integration with 3scale as follows:
    curl -H "Content-Type: text/xml" -d @request.xml -X POST "http://localhost:80/" 


  • We assume your service authentication mode settings are API key. If you choose app_id/app_key or OAuth mode, you'll need to modify your configuration and SOAP headers slightly. Wherever they are by default taken from HTTP headers or parameters in the Lua file, call the extract_value method to take them from the XML instead.
  • If you can't read the incoming request SOAP XML, you may need to upgrade to the latest version of Lua. If this is the case, you'll see an error around code snippet 6.c above of the Lua. Upgrade with the following command:
    sudo apt-get install lua5.2
  • If you experience any issues, it can be useful to enable debugging to the server console. In nginx_XXXXX.conf before the events directive add the following line:
    This will enable you to write log statements to logs and console in Lua file as follows: log("debug message") to dig deeper into any issues you may have.