As enterprises seek to integrate Cloud and Mobile channels, enterprise IT architects are presented with many new challenges. The traditional architecture for web based applications does not always effectively link to mobile and cloud side applications. The days of a monolithic central point of integration are numbered as enterprises use a myriad of applications in their daily business, both on-premises and in the Cloud (e.g. SalesForce). Lightweight Web APIs are how these applications are delivered and in an API-centric world, the traditional, ESB-based integration point is no longer really valid. So how does the enterprise respond under the shifting sands of this evolving IT architecture and turn its SOA investment into $OA driven, revenue generating services.

What you will learn

. How Mobile and Cloud are changing the traditional architecture patterns
. Examples of differing traditional and new architecture patterns
. Best practice approaches to integrating cloud and mobile applications with your enterprise architecture

A frequent question about the Axway/Vordel API Server is “Is it possible to orchestrate multiple calls to different APIs or Web Services?”. The answer is “Yes”, and in this blog I’ll show how. Along the way, we’ll see how to configure JSON Path on the API Server. Keep reading to find out how to orchestrate a REST API with SOAP.

For my worked example, I’m using a weather-lookup scenario. It’s now Spring in Boston, and I’m interested in finding out the temperature using the API Server. Yahoo provides a great Weather API to retrieve weather information using REST and JSON. Unfortunately though, it returns the temperature in Fahrenheit and I’m more familiar with Celsius. So, I want to take the temperature from the Yahoo output, and feed this as input to the W3 Schools Fahrenheit-to-Celsius conversion Web Service. This means that I’m orchestrating to calls, one to a REST JSON API and the other to a SOAP Web Service.

Breaking down the steps, this means:

Step 1) The API Server receives a HTTP GET request containing a zip code as a parameter, like this: http://API-Server/orchestration?zip=02110

Step 2) The API Server first makes an API call for this zipcode’s weather to Yahoo’s Weather API, which returns the weather info as JSON

Step 3) We then extract the temperature from the Yahoo JSON response, and use this to construct a SOAP request to the W3 Schools Fahrenheit-to-Celsius conversion Web Service.

Step 4) Finally, we return the temperature info, converted to Celsius, to the client.

To achieve this, we use a circuit on the API Server, which I show in its entirety below:

Let’s look at the steps in detail. Each of the blocks in the circuit is called a “filter”. Let’s look at what each filter does

1) Extract REST Request Attributes. This filter takes the items from the HTTP request and converts them to variables (which we call “Attributes”). When I call the API Server with a request in the browser like http://API-Server/orchestration?zip=02110 , the value “02110″ is put into the attribute ${http.querystring.zip}

2) Set HTTP Verb to GET. This is a “Set HTTP Verb” filter which sets the HTTP Verb to “GET”, as shown below:

I am setting the verb to GET because we need to do a GET request to Yahoo’s REST Weather API.

3) Call Yahoo Weather API. This is a “Connect to URL” filter, which is configured to pass the zipcode which we’ve read from the querystring using the Extract REST Request Attributes filter earlier. Notice the zipcode underlined below in red:

4) Read temperature using JSON Path. After we call the Yahoo API, we have the weather response as JSON. I used the excellent online JSON Path Evaluator to construct the JSON Path to read the temperature from the Yahoo response into an Attribute called “temperature”:

5) Create temperature lookup request. The next step is to use a “Set Message” filter to take the temperature from the Yahoo JSON response (which we’ve just read using JSON Path) and place it into a SOAP request to the Fahrenheit-Celsius conversion Web Service, as shown below:

6) Set HTTP Verb to POST. This is another “Set HTTP Verb” filter, this time setting the verb to “POST” because we are about to POST our new SOAP request to the W3 Schools Web Service.

7) Connect to Temperature Conversion Service. This is a “Connect to URL” filter, which contains the URL we want to POST to.

Retrieve Celsius temp from message. This is a “Retrieve from Message” filter which uses XPath to read the Celsius value from the SOAP response. To use the XPath Wizard, click on the little magic wand icon, and open a stored example of the SOAP response. I show the configuration for this below:

9) Return Response. This is a “Set Message” filter, and you can see it takes the ${temperature} attribute from the XPath in Step 8, with the Zipcode we read from the Query-String in Step 1:

I wire up the circuit to a path of “/orchestration”, like so:

This means that whenever a request comes in to “/orchestration”, my circuit is run.

I can call circuit simply from a browser like so:

You can see it’s just over 8C in Boston right now. Balmy, compared to a couple of weeks ago.

Using the Vordel Manager on port 8090 of an API Server instance, I can see each request go through, and click on “Show” buttons to see the actual messages and response.

You can see above that there are three request-response pairs:

1) From the Browser to the API Server

2) From the API Server to the Yahoo REST/JSON Weather API

3) From the API Server to the W3 Schools SOAP Web Service to convert from Fahrenheit to Celsius.

So, what we’ve seen here is that you can orchestrate two requests, one to a REST API and another to a SOAP Web Service, using the Axway/Vordel API Server. Note that the second request overwrites the initial response (if you want to keep a copy of the first response, use a “Store” filter and then use “Restore” to restore the message later).

For more info about the Axway/Vordel API Server, email info@vordel.com

How to create a RESTful Security Token Service ; The RESTful STS

A Security Token Service (usually abbreviated to STS) is used to issue tokens. It is used for situations where a service requires a particular identity token, for example a SAML token. Check out a video of an STS in action here. A client requests the token from the STS, using a SOAP request according to the WS-Trust RequestSecurityToken (RST) specification:

However, Vikas Jain has suggested a more streamlined way for an STS to operate. Rather than using heavyweight SOAP messages to invoke the STS, why not use REST instead. This becomes a “RESTful STS”. Vikas has suggested a token exchange for clients of a REST STS.

Let’s explore how a RESTful STS would be configured in Vordel’s XML Gateway. Here is a policy which will issue a SAML token or a more streamlined custom token when invoked with a RESTful query:

The policy is checking which type of token the REST caller is requesting: SAML or a custom token. The custom token is a lightweight non-XML token. Here we request a custom token from the STS using a request like this:

http://xmlgw:8080/RequestSecurityToken?TokenType=custom&RequestType=Issue

And we see the token returned:

Here we are requesting a SAML token using a request like this:

http://localhost:8080/RequestSecurityToken?TokenType=saml&RequestType=Issue

And we see the SAML token returned:

Calling a RESTful STS is, by design, must simpler than calling a full WS-Trust/SOAP based STS. Calling the RESTful STS from an XML Gateway is straightforward. In order to call the RESTful STS, we can make use of the fact that, within the Vordel XML Gateway, you can call out to another service “off the the side” within a policy. Here we call out to a RESTful STS in order to request a security token, and then we inject it into a HTTP Header:

Testing this in SOAPbox, we see the security token inserted by the Vordel XML Gateway into the Authorization header. This header can then be consumed by the downstream application server, or an agent inside the application server.

In summary, a RESTful STS is certainly a promising way to make STS functionality more generally used, since it doesn’t require a heavyweight SOAP message to be created.

Sending a SOAP message onto JMS using the “SOAP over Java Message Service” proposal, or as a Text Message

Did you know that you can use Vordel SOAPbox to send a SOAP message onto a JMS message queue? You can choose to send it as a normal TextMessage, or an ObjectMessage. But you can also choose to use the “SOAP over JMS Message Service” proposal to place the message.

Just choose Design mode instead of Classic mode in the tabs in the top-right, and then drag in a “Messaging System” filter onto the canvas. You might notice that the “drag and join” configuration of SOAPbox is very similar to how the Vordel Gateway is configured. So you can test the JMS service in exactly the same way as you configure the connection to the JMS service.

Monitoring SalesForce.com Usage, traffic and response times

One of my favorite Web APIs to use in demos is SalesForce.com . SalesForce has a ton of information about their API on their developer site. The Vordel API Sever can be used to connect up to SalesForce, including sending up the API Key and caching the Session Identifier which is returned back by SalesForce.

One of the neat things is that all traffic from the app to the SalesForce API is now monitored by the Vordel API Server. There are many advantages to this, which I will delve deeper into in later posts. But, one key advantage is that “rogue cloud service usage” is stamped out, since it appears on the Real-Time Monitoring of the Gateway:

Any issues with the data being sent to SalesForce, such when the Vordel API Server detects and blocks sensitive information which should not go up to SalesForce, is instantly viewable.

Similarly, the response time from SalesForce.com is monitored. It’s easy to see the bytes in, bytes out, and the response times and codes from SalesForce.com, using the Vordel API Server.

More SAML: Validating a SAML 2.0 Assertion

It’s simple to setup the validation of a signed SAML 2.0 assertion in a Vordel XML Gateway. In a circuit, chain together (1) an “XML Signature Verification” filter (which you can find in the “Integrity” group on the right-hand-side of Policy Studio), and (2) a “SAML Authentication” filter (which you can find in the “Authentication” group).

With XML Signature Verification filter, make sure that the SAML assertion is selected under “What must be signed”. In the filter to validate the SAML assertion, make sure that it’s a SAML 2.0 assertion.

Really what we are doing here is first verifying the SAML assertion (i.e. checking it’s trusted, using its signature) and then validating it (making sure it’s the right format). By checking the trust first, we are ensuring that we are not wasting time validating an untrusted SAML assertion. It is important to understand the difference between verifying and validating a token like this. The configuration for the validation step is shown below:

To test this circuit, I am using the SOAPbox testing tool.

We see on the Response screen of SOAPbox that the assertion we’ve sent is indeed valid. If you change its signature in any way, the Vordel Gateway will reject it.

The popular advantages of REST over SOAP are well known: It’s easier to write a REST client, the messages are smaller, you can cache REST traffic using standard Web infrastructure. But what if you have SOAP Web Services and your clients are crying out for REST Web Services instead?

Here is how you create REST Web Services in front of SOAP services using Policy Studio and the Vordel XML Gateway…(http://www.vordel.com/products/API-Server.html)

To do this, create a policy which reads parameters from the REST URL and then inserts those parameters into a SOAP message which it creates on-the-fly. This is shown in the screenshot below:

Let’s look at one of the filters which retrieves parameters from the REST request. This is added to the policy by dragging and dropping it from the “attributes” group (a REST parameter is an example of a message attribute).

Once the attributes are read in from the REST request, we create a SOAP message using a “Set Message” filter, as shown below. The message attributes are written dynamically into this SOAP message which is created on-the-fly. You can see the message attributes below, with the dollar signs and curly braces:

The upshot is that now a REST client, such as an XMLHttpRequest object running in a browser, can access a URL like this http://xmlgateway:8080/QuotationRequest?CustomerID=1234&CommencementDate=Jan2008 and then this results in the XML Gateway sending a SOAP request to a Web Service which looks like this:

<soap:envelope soap=”http://schemas.xmlsoap.org/soap/envelope/”>

<soap:body>

<m:getquotation m=”http://www.example.org/”>

<customerid>1234</customerid>

<commencementdate>Jan2008</commencementdate>

</m:getquotation>

</soap:body>

</soap:envelope>

The overall picture is shown below:

This is a nice example of “service virtualization”. The REST service in this example is a “virtual service”, since it doesn’t actually exist on the Web Service platform itself. Only the SOAP service exists there. The XML Gateway exposes the REST service as a “virtual service”. This has security advantages, since there is nothing so secure as something which doesn’t even exist. The REST service does not exist on the Web Services platform. It only exists on the locked down, hardened XML Gateway as a virtual service.

The REST parameters can be scanned using a “Threatening Content” filter dragged into the policy in Policy Studio. This is shown below:

In addition, authentication can be added, for example using HTTP client authentication or SSL mutual authentication.

Using this technique, clients can access a REST service, gaining the advantages of REST, while the service provider is safe in the knowledge that they haven’t just opened up a backdoor into their SOAP services.

Pro tip: Running Vordel API Server analytics as a Windows service

If you’ve downloaded the Vordel API Server v7.1 from the Vordel website and want to configure it to run analytics as a Windows service, it’s quite simple to do this. The command is:

installservice.bat “C:\Vordel-7.1.0\analytics” “analytics” “7.1″ analytics.xml

Where “analytics” is the name you want to give the service, and “7.1″ is the version number. The installservice.bat script can be found under the /win32/bin folder of the API Server installation.

Once you run this, hey presto, you’ll see Vordel API Server analytics in your list of Windows services:

Note: Ensure you run the installservice.bat with the permissions to create a Windows Service, otherwise you will see an “Access is denied. Could not open service control manager” error.

JSON is a very popular choice for transmitting data on the wire, especially since it is widely used for Apple iPhone app development. The usage of JSON allows a developer to skip the step in the browser where incoming XML must be parsed and read into an object. Instead, a serialized JavaScript object is sent, often including the data it needs already. So, no need for XML. But, in order to create this JSON structure in the first place, it is a good idea to offload this task onto an appliance such as an XML Gateway. The XML Gateway then serves up the JSON (to an iPhone for example), dynamically converting it from the source XML.

Here you can see XML being converted dynamically to JSON by an XML Gateway, as tested using the free SOAPbox tool:

This is enabled at the Gateway side by a relatively simple circuit. One key gotcha to remember is that when serving up JSON; make sure the content type is set to “application/json”. Otherwise, clients may choke on it since they will not realize what it is.

Grab a copy of the Vordel Gateway to test this XML-to-JSON functionality here: http://vordel.com/products/vx_gateway/

Here’s a guide to setting up throttling in the Vordel Gateway:

If you’ve already registered a WSDL, skip forward to step 4.

Step 1: Open Policy Studio. Connect to the Gateway you wish to configure your policy on.

Once you connect, choose “Edit Active Configuration”.

New Web Services are registered in the “Web Service Repository” which is accessed under the “Policies” group on the left-hand-side.

Step 2: Right-click on the “Web Service Repository” and choose “Register Web Service”. Note that the Web Services are arranged in groups, and you can rename these groups. In the screenshot below you can see that we’ve created a group called “B2B Web Services”.

Step 3: Select your WSDL (either via URL, file, or UDDI) and then walk through the wizard. Choose the location to deploy your virtualized service. Out of the box, there is a set of services called “Default Services” on port 8080 in , but you can rename this or change the port. You can also add a new service group (e.g. called “SSL Services”) with a different listening interface (create the new services, then right-click and choose “Add interface”).

Don’t check the box right now to “Secure this Web Service”. You’ll then see a “Summary” screen in the wizard, which says what path the Virtual Service has been deployed on. Take note of this path. Press OK and then press the “Deploy” button on Policy Studio to deploy. Now open the WSDL in the browser. Note that will automatically virtualize the service hostname in the WSDL (as explained here: http://www.soatothecloud.com/2011/06/how-to-enable-service-virtualization.html ).

Step 4: Right-click on “Policies” in Policy Studio and select “Add Policy”. If you already have created a contained to contain your policies, you can right-click on your container and make your policy there. Note that containers are a way to group policies together, e.g. for importing and exporting them together, but don’t affect the running of the policies.

Call your new policy “Throttling”

Step 5. Drag in a “Throttling” filter, which you can find in the “Content Filtering” group. Configure with “10 messages in 1 minute” as shown in the screenshot below. Note that the Gateway must retain state for the messages, because it stores the message count. So, this is stored in a cache [called "Maximum Messages" in the screenshot]. You can add another cache, or edit the cache name, under “External Connections” in Policy Studio.

When you drag in the filter on to the policy canvas, it is initially gray because it is not being used yet. Right-click on this filter and choose “Set as start”. Now it is no longer grayed out. However, it is outlined in red because it requires an input (the messages) which it is not getting at the moment. For it to get this input, it must be “wired up” to policy that is receiving a message through a listening interface.

Step 6: In Policy Studio, look under “Policies” and then “Generated Circuits” to find the service you’ve registered in Step 3. Double-click on the filter called “Service Handler for ”. Then open the “Message Interception Points” tab. Under “Before Operation-specific Policy” press on the “…” button to choose the policy you made in step 5 to do throttling. Once it is mapped, you should see the mapping set. Make sure you press the “Deploy” button on the Policy Studio toolbar to deploy this policy.

Step 7: Open the SOAPbox testing tool (a free download from here). We will be using SOAPbox to test our throttling policy. Open the Virtual Service WSDL which you obtained from Step 3. [Tip: The Service Manager interface, under :8090/ , also allows you to see the Virtual Service WSDL, if you connect with a role which allows you to use Service Manager]. In SOAPbox , press on the import WSDL and import the Virtualized WSDL (note: not the actual WSDL from the back-end service you’ve registered, otherwise you’ll simply send your messages to the back-end services and not through ).

Step 8: You’ll see a sample message created for you in SOAPbox. Send the message through to with SOAPbox, by pressing the green triangular “play” button. Keep pressing the button until you reach the throttling limit. This message will be blocked. Note that you can customize the response message, since in a production system it is not usual to return a SOAP Fault to clients.

Step 9: View the blocked message in the Vordel Gateway’s Real-Time Monitoring by pointing a browser to :8090/ and then clicking on “Real-Time Monitoring”. Note that you’ll have to login as a user with a role which allows viewing of Real-Time Monitoring. The screen is shown in the screenshot below:

Other steps: If you add a Distributed Cache (under “External Connections” then “caches” then “Add” in the botton-right) then you can set two or more Gateways to use the same cache. This means that if the traffic is being distributed across them, then the throttling count is cumulative over them (e.g. if 5 requests come to 1, and 5 to 2, then the value in the cache will be 10).