See blog for context and high level details.
Aside from some minor configuration on the 3scale API Manager web interface, the solution mainly involves a small customization to one of the Lua scripting source files used by the gateway, configuration.lua. For precise details on the customization, use a diff tool on the file in this repo with the one we changed.
We create a Docker image using the standard APICast (aka 3scale Gateway) image and just override this lua file. Note as discussed in the blog, we use a HTTP Header called SOAPAction. This is because, by convention, this header identifies the SOAP Operation. Should you wish to use another, fork this repo and modify this line.
To implement, you simply follow the 3scale API Manager configuration section below. Then, depending on your desired implementation, follow either the Raw Docker or Openshift gateway configuration section below.
On the 3scale API Manager we configure the SOAP endpoint the same way we configure a REST endpoint. On the APIs screen, first create a Service.
Create a new Service for SOAP:
Name it, give a System name, choose Nginx Apicast self managed, choose your Auth Mode (API Key in my case), then Create Service. Then choose Integration -> edit APIcast configuration. Then configure as shown next.
Mapping SOAP Endpoint URL path to 3scale method:
In my case, I use a fictitious Geo-Location SOAP Service - identified by the path /geo-endpoint. I map this to a logical 3scale method geo-service. This will cause all SOAP requests to this endpoint to be authorized and reported to 3scale under this method.
Additionally, in order to get the fine-grained, operation-level access control and traffic visibility, we define 3scale metrics for each operation. Navigate to API -> Your SOAP API -> Definition. Create a Method for each endpoint - in my case just one geo service. Additionally create a Metric for each SOAP operation your Service exposes. In my case I’ve configured possible operations city, country etc.
API Definition with method and multiple metrics representing operations:
At this point, in your 3scale Application Plans (access policies), you could now control access with rate limits to each of these metrics and the method. Of course, to see any numbers, you'll need to configure your gateway and make Web Service calls as detailed below.
In your Analytics section, you now get overall traffic visibility at Method level and at individual metric or operation level.
Method level visibility showing overall traffic to SOAP Service endpoint:
Metric level visibility showing traffic to individual SOAP operations:
There are some minor modifications to the instructions given in the APIcast on Docker documentation. Log on to your RHEL box and make the following commands (or your equivalents):
- sudo su
- systemctl start docker
- git clone < this repo or your fork >
- cd soap-apicast
- docker run --name apicast --rm -p 8080:8080 -v $(pwd)/configuration.lua:/opt/app-root/src/src/configuration.lua:z -e THREESCALE_PORTAL_ENDPOINT=https://<3scale access token>@<3scale domain> -e APICAST_LOG_LEVEL=debug registry.access.redhat.com/3scale-amp20/apicast-gateway
This will take a few seconds to start as it pulls down the image and your configuration from your API Manager, be it On-Prem or from the 3scale SaaS.
Test your Service with your equivalent of the following:
curl -X POST --header "SoapAction: <the 3scale system name you configured for this operation>" --header "Content-Type: application/soap+xml" --header "Accept: application/soap+xml" --header "user-key: < your API key >" -d '< your SOAP request XML >' http://< your gateway host >:8080/< your SOAP endpoint > --verbose
Check your 3scale Analytics. Both the operation metric and endpoint method will have incremented.
Some minor changes are needed to the instructions given in the APIcast on Openshift documentation. Log on to your RHEL box and make the following commands (or your equivalents):
- sudo su
- systemctl start docker
- oc cluster up --public-hostname=< your Openshift domain > --routing-suffix=< your Openshift IP address >.xip.io --version=latest
- oc login
- oc new-project soap-apicast
- oc new-build https://github.com/tnscorcoran/soap-apicast --strategy=docker
- oc get is/soap-apicast (slot in what this command gives for IMAGE_NAME two lines below)
- oc secret new-basicauth apicast-configuration-url-secret --password=https://<3scale access token>@<3scale domain>
- oc new-app -f https://raw.githubusercontent.com/3scale/apicast/v3.0.0/openshift/apicast-template.yml -p IMAGE_NAME=< your IMAGE_NAME > -p LOG_LEVEL=debug
- oc expose service/apicast (it will give you the route something like: http://apicast-soap-apicast.< your Openshift domain >)
After a couple of minutes 2 Gateway Pods should successfully deploy as follows:
Test your Service with your equivalent of the following:
curl -X POST --header "SoapAction: <the 3scale system name you configured for this operation>" --header "Content-Type: application/soap+xml" --header "Accept: application/soap+xml" --header "user-key: < your API key >" -d '< your SOAP request XML >' http://< your route exposed by command 'oc expose service' above >:8080/< your SOAP endpoint > --verbose
Check your 3scale Analytics. Both the operation metric and endpoint method will have incremented.