Details

tanapro WebserviceTool (for Android) is a generic webservice client for SOAP and REST webservices. There are many webservices around with information about weather, stock quotes, sports results, countries, etc. With WebserviceTool you can get this information fast and efficiently to your smartphone.

WebserviceTool

What is WebserviceTool?
Defining a webservice
Edit a request
Invoking a request
HTML view
Creating a shortcut
Legal issues

1. What is WebserviceTool ?

This Android application ("APP") is a generic webservice client for SOAP and REST webservices. There are many webservices around with information about weather, stock quotes, sports results, countries, etc. With WebserviceTool you can get this information fast and efficiently to your smartphone.

The program has following features:

Runs on Android 2.2 or higher (smartphone / tablet)
Supports SOAP (1.1 and 1.2) and REST webservices.
The GUI for entering the request parameters is automatically built from the request data defined for the webservice request. The user can customize the labels of the input fields or hide fields in the GUI.
SOAP requests (and especially their request data) can be automatically created from the WSDL (only for 1.1 WSDLs with document/literal style)
Supports webservices with Basic Authorization
Supports WSHttpBinding (SOAP 1.2)
Supports WS-Addressing
Supports HTTPS servers with trusted and untrusted certificates. Untrusted certificates can be verified by their fingerprint.
Webservice definition files (*.wst) can be securely stored by optionally encrypting them.
The XML response of the webservice is displayed as tree, table and raw XML. The data can be copied to the clipboard.
The XML response can be shown in a HTML view which can be fully customized by the user with XSLT templates.
Requests can be shortcutted and started from the Android Home screen
For troubleshooting the user can set the log level in the settings to DEBUG whereupon the APP logs a lot of information to catlog that can help solve the problem (a separate catlog app is needed to view the catlog).
Battery-friendly black color scheme

top

2. Defining a Webservice

2.1 Automatically create SOAP Webservice Definition

If you have the WSDL of a SOAP webservice, the APP can automatically create the requests from the WSDL:

Choose the menu option "Webservice | New webservice" to open the Webservice Activity.
Webservice directory: Select or enter the directory where you want to store the webservice definition file (*.wst)
Name: Choose a name for this webservice. This name will be used as name of the .wst file.
Description: Optionally enter a description for this webservice.
URL: Optionally enter the URL of the webservice endpoint. If you do not enter the URL here, you will be prompted later on. So, it's best to enter it here right now.
User: Optionally enter the username if the webservice uses HTTP-BasicAuthorization.
Password: Optionally enter the password if the webservice uses HTTP-BasicAuthorization.
Press the button "Create webservice from WSDL".
In the WSDL Activity, you can choose to download the WSDL from the Internet. If you have already downloaded the WSDL once, the available webservice operations will be displayed.
Choose the operations for which you want the APP to create requests and select the menu option "Add/update requests". Make sure to only choose operations form 1 binding (SOAP 1.1 or SOAP 1.2 binding). You cannot mix operations from different bindings.
Back in the Main Activity, long-press a request and optionally customize the request data (see manual way below).

If the WSDL cannot be downloaded, but you have it as a file, copy it to the webservice directory and give it the same name as your webservice definition file with extension wsdl. Example: If your webservice definition file is /sdcard/ws/service1.wst then store the WSDL file as /sdcard/ws/service1.wsdl. Then, long-press a request in the Main Activity and choose "Manage | Add/update from WSDL".

top

2.2 Manually create SOAP Webservice Definition

If you don't have a WSDL or if the WSDL type is not supported by the APP, you can still use this webservice by manually creating the webservice definition.

Follow the steps 1 to 7 from the automatic way above.
Encoding: Choose the correct encoding (normally UTF-8)
Type: Choose "SOAP"
Binding: Choose "BasicHttp" for SOAP 1.1 or "WsHttp" for SOAP 1.2
Certificate fingerprint (SHA1): Normally, leave this field EMPTY! If your webservice uses HTTPS and its certificate chain cannot be verified, enter the SHA1 fingerprint of the certificate here (for example 86:19:d4:94:7c:f1:f9:71:9a:f4:aa:43:33:e1:d5:47:a1:db:b9:12). If the fingerprint does not match the one gotten from the webservice, the request is aborted for security reasons (you will then probably be talking to the wrong service!)
Show attributes in tree: If you choose this checkbox, all attributes of a XML element in the response will be treated like a XML element of their own. This is useful for certain REST webservices.
Press the "Save" button to save (or the "Cancel" button to abort).
Back in the Main Activity, long-press the request "new request" and edit the request.

top

2.3 Create REST Webservice Definition

Follow the same steps as for SOAP webservices with following changes:

URL: Enter the base URL for this REST webservice. The base URL is that part of the URL which is the same for all requests.
Webservice type: Choose "REST"
Binding: Choose the correct binding, probably "BasicHttp"

top

3. Edit a request

3.1 Edit a SOAP request

You can edit SOAP requests as follows:

In the Main Activity, long-press the request and choose "Manage | Edit". This will open the Request Activity.
Name: Enter the name of the request. You can choose any name you like.
Description: Optionally enter a description for the request.
User: Optionally enter the username if the webservice uses HTTP-BasicAuthorization. If left empty, the User defined in the Webservice will be used.
Password: Optionally enter the password if the webservice uses HTTP-BasicAuthorization. If left empty, the Password defined in the Webservice will be used.
HTTP command: Choose "POST"
SOAP action: Enter the correct SOAP action
Request data: Press this button to enter the POST data to be sent to the webservice. The GUI for entering the request parameters is dynamically built from the request data: All XML elements containing the attribute wst_title are presented to the user for data input before the request is sent. The value of the attribute is used as title of the input field. After data entry, the attribute is removed from the POST data before sending it to the webservice. If you want to hide an input field in the dynamic GUI, just remove the wst_title attribute in the request data. The field will then be sent to the webservice, but not shown in the GUI.
XSLT data for HTML view: Press this button to enter the XSLT data which defines the HTML view. If the XSLT data are not yet defined, the APP uses the default template XSLT-default.xsl from the work directory (see menu option 'Infos')
Default view: This defines the default view used to show the XML response.
Show table on element: For the default view 'Table' this defines the XPath of the element which should be shown in a table, together with all its sibling elements. You can get the XPath from the context menu in the tree view.
Auto update request data: Check this option if you want the APP to remember the data you enter in the dynamic GUI.

top

3.2 Edit a REST request

REST webservices can use more HTTP commands than just POST. They normally use GET to retrieve data and PUT or POST to send data. Data can be passed as URL parameters or as PUT/POST data. The requests are defined the same way as for SOAP requests, but with following changes:

HTTP command: Choose what the service wants
Request data: The request data is defined as XML data with following structure: The root element can be named as you like and can contain following 3 child elements:
- relativeURL: This element is normally always needed. The children of this element can be named as you like. It is the content which is used to build the URL later on.
- parameters: Add this element if you need to pass URL parameters. The children of this element must have the same name as the name of the parameters you want to pass. The content will be sent as value of the parameter.
- POSTdata: Add this element if you need to send data with the PUT or POST command. The children must conform to the specification of your REST webservice.

Below, there is an example for the Pivotal Tracker API (http://www.pivotaltracker.com/help/api).

<PivotalTracker>
  <relativeURL>
    <part1>projects</part1>
    <part2 wst_title="Project number:">1234</part2>
    <part3>stories</part3>
  </relativeURL>
  <parameters>
    <token wst_title="Security token:">010203040506070809A0</token>
  </parameters>
  <POSTdata>
    <story>
      <story_type wst_title="Story type:">feature</story_type>
      <name wst_title="Story name:">User Story 123</name>
      <requested_by wst_title="Requestor:">Tom Arn</name>
      <description wst_title="Story description:">This is the user story number 123</description>
    </story>
  </POSTdata> 
</PivotalTracker>

If you define the (base) URL for this webservice as https://www.pivotaltracker.com/services/v3 the request data above will create a dynamic GUI where you can enter the relative parts of the URL, the URL parameters and the data for the POST. When the request is sent to the webservice, following HTTP raw code will be sent:

POST /services/v3/projects/1234/stories?token=010203040506070809A0 HTTP/1.1
Host: www.pivotaltracker.com
Content-Type: text/xml; charset=utf-8
Content-Length: 181

<story>
  <story_type>feature</story_type>
  <name>User Story 123</name>
  <requested_by>Tom Arn</name>
  <description>This is the user story number 123</description>
</story>

top

4. HTML View

The HTML view is for advanced users who want to customize the display of the XML response. You can use the Extensible Stylesheet Language Transformation (XSLT) to specify what data should be shown in the HTML view and how the data should be displayed. See the sample webservices that come together with the APP for some XSLT examples.

4.1 Invoking other requests

The HTML view supports JavaScript and the Android JavaScript Interface. With the JavaScript Interface you can start an other request from the HTML view and pass data to the request's dynamic GUI Activity. Define your JavaScript as follows:

<script type="text/javascript">
function launchRequestXYZ(data)
{
  WebserviceTool.invokeRequest("1353517041646",data);
}
</script>

The first parameter of the method invokeRequest is the unique ID of the request to be called. You see the ID when you edit the request. The second parameter is a String that contains the data. If you need to pass more than one String, you can delimit the Strings with ~, e.g. "data1~data2~data3".

The link to call the script could look like this:

<a href="#" onClick="javascript:launchRequestXYZ('{elementABC/@attrX}')">
<xsl:value-of select="elementABC/@attrX"/></a>

This link will use XSL to get the value of the attribute attrX of the element elementABC and then call the script launchRequestXYZ and pass the data to it.

Starting other apps

From the HTML view you can also start other apps by using URLs which execute implicit Intents. To start a geo location app like Google Maps, you can use following link:

<a href="geo: {position/@lat},{position/@lng}?z=18">
<xsl:value-of select="position/@lat"/>, <xsl:value-of select="position/@lng"/></a>

This link will use XSL to get the geo location from the attributes lat and lng of the element position and starts a geo location app with this data.

top

5. Invoking a request

To invoke (execute) a webservice request, follow these steps:

Open an existing webservice or define a new one.
Long-press a request in the "Requests" tab
Choose "Invoke". This will open the dynamic GUI
Enter the input data and press "OK" (to abort, press "ESC")
The response of the webservice is shown in the tabs "Response (Tree)" and "Response (XML)".
Repeated elements can be shown as a table by long pressing any of those elements and selecting "Table view"

6. Creating a shortcut

To start a request directly from the Home screen, you can create a shortcut as follows:

In the Home screen choose "Add shortcut" and select "WebserviceTool". This opens the Shortcut Activity of the APP.
Select a Webservice definition file (*.wst). This will open the .wst file and load the available requests into the request dropdown.
In the dropdown, select a request or the blank entry if you want the shortcut to only open the .wst file (without starting a request).
Enter the name to be used as title of the shortcut and press OK.

Creating a shortcut will generate a unique Shortcut ID for the request which will insure that the shortcut will always find the defined request even if the request is renamed or moved to another position in the list.

7. Legal issues

Thank you for choosing this SOFTWARE! You may only use this SOFTWARE if you agree with the conditions listed further below:

NO WARRANTY
The SOFTWARE is provided AS IS without a warranty of any kind. All express, implied or statutory warranties, including any implied warranty of merchantibility or fitness for a particular purpose, are hereby excluded. The AUTHOR does not warrant that the SOFTWARE is fail-safe or error-free. The user must bear all risks when using the SOFTWARE.

NO LIABILITY
In no event will the AUTHOR be liable for direct, indirect or consequential damages related to the use (or the inability of the use) of the SOFTWARE, even if the AUTHOR has been advised of the possibility of such damages.

top

Nav view search

Navigation

Search

tanapro WebserviceTool