Calling Web Services from the Shell
By damitha nanda mangala kumarage
- 13 Mar, 2008
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.
|Environment||Linux - Debian Etch/Lenny, Ubuntu, Fedora, Windows|
Table of Contents
- Installing wsclient
- Calling Web Services
- Amazon Client Sample
- Flicker Photo Search Sample
- Handling Attachments
- Security with wsclient
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.
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.
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.
|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||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.
|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.
|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|
|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.|
|server-cert PATH||Path to certificate file to use with https transport|
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 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:
" | $WSFC_HOME/bin/wsclient --get https://api.flickr.com/services/rest/?method=flickr.photos.search flickr.photos.search $1 peace
Here, we don't use SOAP binding and use get as the http request method.
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.
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.
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.
- WSO2 WSF/C - WSO2 WSF/C is an Open Source framework for providing and consuming Web services
- Axis2/C- Axis2/C is an Apache Web Services Platform implemented in C language around which the WSO2 WSF/C is built.
Damitha Kumarage, Senior Software Engineer at wso2, committer Apache Software Foundation, damitha at wso2 dot com
- damitha nanda mangala kumarage
- senior tech lead