Calling Web Services from the Shell

In this article by Damitha Kumarage, he describes calling Web services from a shell environment.

Introduction

WSF/C framework is a feature rich Web services platform implemented in the C language and is built around the various Apache WS-* implementations like the Axis2/C Web services engine, the Sandesha2/C Reliable Messaging Implementation, the Rampart/C WS-Security implementation and the Savan/C WS-Eventing implementation. Based on WSF/C implementation, there are other successful scripting language specific Web Services platforms like WSF/PHP, WSF/Perl, WSF/Ruby, and, there are also browser plugins written using WSF/C framework to enable browsers(currently for Firefox and IE) with Web services. It is only very natural for one to expect the ability from command line shells to invoke Web services. wsclient is a tool for this purpose. It is currently implemented and tested in Linux and Windows platforms. Many of you may be familiar with the wget command line tool. wget is a non-interactive network receiver which could be very handy in certain situations. The analogy between wget and wsclient is, that like wget is for http interaction from command line, wsclient is for Web services invocation from command line. wsclient has support for both SOAP and Rest like invocations. It should be noted that wsclient can also be effectively used as a great testing tool for your wire SOAP formats.

Applies To

Table of Contents

• Installing wsclient
• Calling Web Services
  • Http Options
  • SOAP Options
  • Addressing Options
  • MTOM Options
  • Rampart Options
  • SSL Options
• Amazon Client Sample
• Flicker Photo Search Sample
• Handling Attachments
• Security with wsclient
• Summary
• Resources

Before continuing with this article, please note that I expect you to be familiar with the Axis2/C Web services platform. Apache Axis2/C - Web Services Engine is a good reading to get you started. All the samples in this article uses wsclient tool, in Linux bash shell. All these could be similarly performed on a Windows shell as well.

Installing wsclient

You can download wsclient from WSF/C download page. Installations are available for Windows, Debian and rpm. Once installed you are ready to play with wsclient.

Calling Web Services

wsclient --help provides a comprehensive list of options, when invoking Web services. These options could be categorized under http, SOAP, Addressing, MTOM, Rampart, SSL and as general options.

Http Options

Http options let you specify the content type of the http payload or use get as a http method. You can also specify http header lines to be included in the http header and you can extract these http headers to be included in the response.

SOAP Options

SOAP options allow you to use SOAP binding in your invocations, specify SOAP version, SOAP action, to define whether output format is SOAP and message exchange pattern(whether send only or two way) . An important feature of Axis2/C Web services engine is its support both SOAP and REST like invocations. wsclient's default behavior is to send messages as REST. To send SOAP messages you should enable --soap option. Also, there is an option called soap-dump, which lets you test your wire format by dumping the message into a file instead of actually sending it through the wire. This lets you test your wire SOAP formats by just adding --soap-dump option to the wsclient command.

Addressing Option

We can use WSA addressing options to specify destination address, from address, reply to address, fault to address and the relates to address. Also, we can specifically ask the tool not to include any addressing headers inside the SOAP header. It should be noted that if you specify --action, then even if you do specify --no-wsa, it will be overridden to enable addressing. Then wsa:Action addressing header will be included in the header.

MTOM Options

Rampart Options

SSL Options

Amazon Client Sample

Now, let's look at some samples that use these options to get things done. wsclient can be used from shell scripts for useful work. There is a command line tool called amazonclient, which can be used to do transaction with the Amazon ecommerce Web Service. For more information on using this tool, refer my article Amazon ecommerce Client. Here, we will look at a small sample script that does an item search on Amazon ecommerce Service.

wsclient --soap1.1 --no-mtom --action http://soap.amazon.com 
http://soap.amazon.com:80/onca/soap?Service=AWSECommerceService < item_search.xml

Contents of the item_search.xml is

<ItemSearch xmlns="http://webservices.amazon.com/AWSECommerceService/2005-10-05">
       <AWSAccessKeyId>Access Key</AWSAccessKeyId>
       <Request>
           <ResponseGroup>Medium</ResponseGroup>
           <ItemPage>1</ItemPage>
           <Keywords>Web Services</Keywords>
           <SearchIndex>Books</SearchIndex>
       </Request>
</ItemSearch>

To try this sample, you must obtain an access Key from Amazon AWS .

Flicker Photo Search Sample

Flicker site also provides a Web services API, which can be leveraged to do Web services transactions with Flicker. In the following command, we will search photos on Flicker site:

echo "<x:FlickrRequest xmlns:x='urn:flickr'><method>flickr.photos.search</method>
<api_key>Access Key</api_key><tags>peace</tags></x:FlickrRequest>" | wsclient --soap 
--no-mtom --no-wsa  http://api.flickr.com/services/soap/

To try this sample you must obtain an access key from Flicker . This will return all information related to the photos that match the search keyword "peace". We can also make a Rest invocation using the following command:

echo "flickr.photos.search$1peace" | $WSFC_HOME/bin/wsclient --get 
http://api.flickr.com/services/rest/?method=flickr.photos.search

Here, we don't use SOAP binding and use get as the http request method.

Handling Attachments

wsclient can be used to send attachements with a SOAP message. Attachments could be binary optimized or not. To make it not binary optimized(base64 encoded) use --no-mtom option. The default behaviour of wsclient is sending attachements with binary optimization. Following command will send the image in binary optimized format:

wsclient --soap --xop-in $WSFC_HOME/bin/samples/resources/axis2.jpg
http://localhost:9090/axis2/services/mtom
<$WSFC_HOME/bin/samples/wsclient/data/mtom_test.xml

$WSFC_HOME/bin/samples/resources is the path where the image to be sent reside. You can also give the --xop-out option, to indicate the folder in which a reply image, if any, to be stored.

Security With wsclient

Currently, wsclient supports some useful security options which will suffice for most situations. The underline Axis2/C module which provides security for wsclient is, Rampart/C . A Quick Reference Guide for Rampart/C Configurations is a good place to learn more about implementing security with Rampart/C. You can specify username, password pairs or password files for most basic authentication scenarios as the following:

wsclient --soap --no-mtom --user alice --digest --password
password http://localhost:9090/axis2/services/sec_echo
<$WSFC_HOME/bin/samples/wsclient/data/echo.xml

Note that, --digest option above, is for password digest for the username token.

To perform signing:

wsclient --soap --no-mtom --timestamp --sign-body --key
$WSFC_HOME/bin/samples/rampart/keys/ahome/alice_key.pem --certificate
$WSFC_HOME/bin/samples/rampart/keys/ahome/alice_cert.cert
--recipient-certificate
$WSFC_HOME/bin/samples/rampart/keys/ahome/bob_cert.cert
http://localhost:9090/axis2/services/sec_echo
<$WSFC_HOME/bin/samples/wsclient/data/echo.xml

To perform encryption and signing

wsclient --soap --no-mtom --timestamp --sign-body --key
$WSFC_HOME/bin/samples/rampart/keys/ahome/alice_key.pem --certificate
$WSFC_HOME/bin/samples/rampart/keys/ahome/alice_cert.cert
--recipient-certificate
$WSFC_HOME/bin/samples/rampart/keys/ahome/bob_cert.cert --encrypt-payload
http://localhost:9090/axis2/services/sec_echo
<$WSFC_HOME/bin/samples/wsclient/data/echo.xml

It should also be noted, that for all security scenarios described above, you can use the Rampart/C server sample called sec_echo. You may need to do some policy changes in the sec_echo server sample's service.xml for certain scenarios. For example, you may need to comment the Timestamp entry, if you are not sending a timestamp from wsclient.

Summary

wsclient is command line tool for consuming Web services. It is could be used to do both SOAP and REST invocations of Web services. It has several options to provide the user the flexibility, under the categories http, soap, ws addressing, attachments and secutiry. It could also be used as a great testing tool for developers writing Web services.

Resources

1. WSO2 WSF/C - WSO2 WSF/C is an Open Source framework for providing and consuming Web services
2. Axis2/C- Axis2/C is an Apache Web Services Platform implemented in C language around which the WSO2 WSF/C is built.
3. wsclient

Author

Damitha Kumarage, Senior Software Engineer at wso2, committer Apache Software Foundation, damitha at wso2 dot com