Calling Web Services from the Shell

Archived Content
This article is provided for historical perspective only, and may not reflect current conditions. Please refer to relevant product page for more up-to-date product information and resources.
  • By damitha nanda mangala kumarage
  • 13 Mar, 2008

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

WSF/C 1.2.0, 1.2.1
Axis2/C 1.3.0
Environment Linux - Debian Etch/Lenny, Ubuntu, Fedora, Windows

 

Table of Contents

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

option description
get When this option is specified http get method is used for http request
conten-type TYPE http payload content type header
http-header LINE Add the LINE http header line into the http header.
output-http-headers FILE write the response message's http headers into file FILE

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

option description
soap use the soap binding
soap1.1 Default is soap1.2. If you need soap 1.1 specify this option
action URI Use URI as the soap action
soap-out Output the entire soap reponse. By default only xml in soap body is displayed as output.
send-only This is to specify send only Message Exchange Pattern.
soap-dump Dump the input soap message instead sending it through wire.

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

option description
no-wsa Disable WS Addressing.
to URI Use URI as the destination address
from URI Use URI as the WS Addressing From address.
reply-to URI Use URI as the WS Addressing ReplyTo address
fault-to URI Use URI as the address to which the fault should be sent.
in-reply-to URI Use URI as the WS Addressin RelatesTo address

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

option description
no-mtom Don't use binary optimization when sending attachments
xop-in DIR DIR is the base directory of the package need to transmit
xop-out DIR DIR is a directory for save attachments receive

Rampart Options

option description
user USERNAME includes username token with user as the USERNAME
password PASSWD uses PASSWD as the password for username token
password-file FILE uses password from FILE
digest uses a password digest for the usename token
sign-body Signs the soap body
certificate FILE Includes an X509 security token from file, which is an X509 certificate in PEM format. This is a certificate for the sender which can be used for signing or supporting according to other options.
key FILE Signs using the private key file, which must be the private key in PEM format.
recipient-certificate FILE Encrypts using the public key associated with file, which should be an X509 certificate in PEM format.
encrypt-payload Encrypts the contents of the SOAP body.
algorithmsuite ALGORITHMSUITE Use the corresponding algorithm suite for signature and encryption. The value is one from Web Services Security Policy language July-2005 [section 7.1 Algorithmsuite Property].
encrypt-signature Encrypts the signature (when signing before encryption).
encrypt-before-signing Encrypts before signing, in other words the signature is computed over the ciphertext; By default, when there a message is to be protected with both signing and encryption, wsclient will sign before encrypting, in other words, the signature will be computed over plain text.
timestamp Generates a time stamp element in the security header.

SSL Options

option description
server-cert PATH Path to certificate file to use with https transport

 

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 https://soap.amazon.com 
https://soap.amazon.com:80/onca/soap?Service=AWSECommerceService < item_search.xml

Contents of the item_search.xml is

<ItemSearch xmlns="https://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  https://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 
https://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
https://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 https://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
https://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
https://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

About Author

  • damitha nanda mangala kumarage
  • senior tech lead
  • wso2