WebRPC User's Manual

Overview
Key concepts
Supported types of services
Supported client platforms
Service Attributes
Operations on services
Product versions
User Management

Overview

WebRPC is a repository for any kind of web based service. It is primarily intended to be used by developers and administrators working on web 2.0 based mashup sites or a corporate service oriented architecture. WebRPC's mission comprises the following key points.

One stop service repository

WebRPC provides tools and information for all aspects of service centric computation which drastically simplifies the development and administration process. Users can find suitable services, review the terms of use, service level agreements, and license conditions, review historical service availability and reliability data, test the service functinality, and finally incorporate the service with a few simple clicks.

Access any web resource

In an ideal world, all services and information would be accessible via a single middleware. We are seeing a consolidation towards http-based data transfers, however this still has developers cope with a variety of different service flavors. Enterprise systems typically speak SOAP, however, with the rise of Web 2.0, we're increasingly seeing REST and JSON based services. Last but not least, many information sources only offer an HTML based user interface without providing a programmatic API which is a big problem when such information is to be integrated in your service oriented architecture. At WebRPC, we believe that it should not matter whether you're dealing with SOAP, REST, JSON, or HTML. WebRPC allows you to access all services in a uniform way.

Select and validate services without client side installation

As the number of services and data sources grows, it is increasingly hard to keep up with this offering. Evaluating a service is currently a cumbersome process which involves selecting the right middleware version, compiling client code, dealing with security certificates, finding the right input values and formats, and packaging the solution. Sometimes incompatible versions of tools like Apache Axis makes using two services in the same software impossible. Developers also have to find out on their own, whether a service is reliable and fulfills their SLA requirements. WebRPC drastically simplifies this selection since developers can evaluate and test services right from a web browser without worrying about different toolkits and software versions needing to be installed locally. Performance statistics are also just a click away.

Put the developer in control with thin client code

When dealing with web service middleware, a quote from Albert Einstein comes to mind: Everything should be made as simple as possible, but not simpler. Unfortunately, current SOA middleware makes things more complex than they need to be. After all, 95% of the time you just want to make an HTTP request and parse some XML. What are all the stubs, handlers, and locators for? On the other hand, critical issues like dealing with security and authentication is often made too simple. WebRPC believes in slim and fast code. WebRPC generates client code for you right on the website. With a couple of dozen lines of code you can configure authentication and security, invoke any http based service, and get your results. Less code is faster, more robust against changes on the server side, more portable, and most importantly easier to maintain and customize for you.

Use services without proxying

WebRPC is not used as a proxy. All web requests are made from your application directly to the service.

Standards based

WebRPC supports and is entirely based on accepted industry standards such as HTTP, HTTPS, AJAX, XML, SOAP, WSDL, DOM, and XPath.

Key concepts

Architecture

WebRPC allows you to choose from a large service repository. You can find, customize, and test services online at www.webrpc.com. Choose a target language such as Java or JavaScript and include it in your solution by simply copying & pasting the code into your application or mashup.

Service repository

WebRPC is an open service repository that allows users to register their services such that they can be shared by others on the Web or the Intranet. Modifications to the service listing can only be done by the creator of the listing, however, others can comment and provide feedback to the creator. Users can also customize a service for their own needs and save the customization on WebRPC. As soon as a service listing is saved, the service is called in hourly intervals to monitor its availability and reliability.

Handling service output

Most service middleware relies on mapping XML documents to objects of the respective client language. For instance Java web service toolkits usually rely on the Java API for XML Binding (JAXB). At WebRPC we think that DOM is a perfectly suitable model for holding the results of a web service call. DOM in conjunction with XPath allows you to precisely locate individual values in the result tree. This technique is already successfully adopted by the WS-BPEL workflow language which entirely abandons the concept of XML to object mappings. Using plain XML, DOM, and XPath has key advantages: First an foremost, the code is faster since the expensive and bulky mapping layer is omitted. Secondly, sticking with XML, the native SOA format, avoids the deficiencies of mappings, especially when it comes to semi structured content which cannot be cast into a fixed object schema. Finally and most importantly, leveraging XPath allows us to treat (X)HTML, REST, and SOAP in a uniform way.

Supported types of services

WebRPC can generate code for the following kinds of web based services:

REST + XML

REST services can be invoked via URL encoded parameters or parameters included in a POST request. WebRPC does not use an XML to Bean mapping like JAXB. Instead, the values are directly accessed via the powerful XPath query language which is the faster and more powerful variant.

SOAP

WebRPC supports SOAP over HTTP and HTTPS and has been tested with Apache Axis and .NET. WebRPC also supports WSDL. As with REST, outputs are filtered using XPath which is exactly what is done in the SOA workflow language WS-BPEL.

REST + JSON

REST services that encode results in the JavaScript Object Notation (JSON) are also supported. JSON is often used as an alternative to XML and provides efficient serialization and simple data access. WebRPC supports JSON on all target platforms.

HTML

WebRPC treats any kind of dynamic web page like a REST service. Internally, the HTML output is converted to XHTML making it accessible with XPath just like any other REST service. Inputs can be encoded in the URL or sent as POST parameters.

Supported client platforms

Java

Java clients entirely leverage the existing core API of the JDK version 1.4 and up. This means you can employ web services without any additional JAR file.

Visual Basic .NET

Visual Basic .NET client code is based on the .NET 1.1 runtime. As with Java, no external libraries are needed.

C#

Except for language syntax changes and stronger variable typing, C# client code is equivalent to the Visual Basic .NET code.

JavaScript

The JavaScript client code leverages Ajax to communicate with the service. Consequently, the browsers need to support Ajax which is the case for IE 5, Firefox 1.0, Netscape 7.1, Safari 1.2, Opera 8, and iCab 3.0 and the respective later versions. WebRPC code is tested on different browsers and contains conditional code to instantiate AxtiveX and Mozilla objects for Ajax and XPath respectively.

PHP

PHP is supported for version 5 upwards.

Service Attributes

Author

Every service has one author attribute. The UI shows the display name of the author, so users can easily search for other services registered by this user.

Name

The service name is a unique identifier for the service. Service names can be changed, at a later point as long as the new name does not collide with another existing service name. The name is primarily used for display and allows users to hyperlink the main service page externally as follows: http://www.webrpc.com/selectService.jsp?name=SERVICE_NAME

Type

The service type is one of SOAP, REST, JSON, or HTML. It is detected automatically once the service is created and cannot be modified by the user.

Description

A short textual description of the service.

Documentation URL

Services often have some sort of homepage, where documentation, terms of use and other information is provided. This attribute contains a hyperlink to that page.

Requires Developer Key

Many services require developers to sign up for a developer key which needs to be sent along with every request. On the service side, this key is used to identify the caller, count the number of invocations, and sometimes also bill the key owner. WebRPC allows users to mark such services with this flag. This means that WebRPC signed up for a key which allows you to test the service online and allows WebRPC to monitor the service. However, once you generate client code, you will need to sign up for your own key in order for your example to work.

Service URL

The Service URL indicates the web location where the actual service resides. For SOAP, this is the SOAP endpoint URL. For all other services, this is the URL that GET or POST requests with the respective parameters are sent to.

Tags

Tags are a simple comma-separated list of words or expressions. For instance a weather service might be tagged with weather and forecast. Tags are used for searching and finding related services.

Requires Basic Authentication

A flag that indicates whether the service requires HTTP basic authentication.

Username

Username for basic authentication. Note that this field is blank if a user other than the service creator opens the service pages.

Password

Password for basic authentication. Note that this field is blank if a user other than the service creator opens the service pages.

Inputs

Services typically have a set of input values. A stock quote service for instance might have the stock symbol and the quote date as inputs. Every input is specified with the following information:

Name

The name identifies the input. For SOAP, it is obtained from the WSDL description of the service. REST services typically define inputs in the GET URL parameters http://host/path?name=value

Value

The string representation of the input value.

Comment

Comments can optionally define things like the set of possible values (e.g. Sun, Mon, Tue, etc.), simply provide other input value examples, or provide some hints as to what effect the input has on the service, as this is often not obvious from the name of the input.

Tags

As with the service tags, input tags can further classify the specific input value. This information is used for searching and for suggestions on how service calls can be combined.

Outputs

WebRPC uses the following paradigm for output processing: Rather than converting the entire XML document into the respective object tree, users can select the relevant parts of the result via XPath queries. This has the tremendous advantage that no unnecessary serialization work has to be performed. The DOM objects that are selected via XPath are then converted to simple types and lists in the target client language, allowing for easy access to the actual data. Each relevant part of the result is characterized as follows:

Name

The name of the output can be chosen by the user. This name will later be used as the variable name in the generated code.

XPath

The XPath query which selects the relevant part of the XML result document.

Value

The values obtained by applying the query to the last result document obtained by the WebRPC service. The values are not editable and simply illustrate the query results to the user.

Tags

As with the service tags, input tags can further classify the specific input value. This information is used for searching and for suggestions on how service calls can be combined.

Operations on services

On the WebRPC site, users can have one service open for viewing and editing at a time. The main tabs allow users to perform the following operations:

Creating new services

Creating a service is very easy. Simply use your browser to locate a sample URL or the WSDL description of a SOAP service and copy and paste the URL in the text field. That's all. WebRPC automatically inspects the URL and determines whether it's a SOAP, REST, JSON, or HTML service. For SOAP services you also choose the SOAP operation which is to be used. After this, you will be redirected to the main service overview page.

Browsing and searching services

The service search page shows services in a tabular overview along with the most relevant information such as the service endpoint URL or average rating. From there, simply follow one of the hyperlinks to select and open a service listing. Before opening a service for viewing, make sure changes to the current service are saved.

Opening, editing, and saving services

The "Service" tab provides an overview of the most important service attributes. This is also the page where changes to the service can be saved back to the repository.

Input

The input tab allows you to provide and change service inputs as well as the "Call" button. This feature allows you to have WebRPC invoke the service on your behalf. The resulting XML document is then displayed in the window below. This screen is also the place to debug service inputs. In case you specify an incorrect input or omit a required input, the service's error message is displayed.

Output

After a successful call, the output tab allows you to harvest the information obtained. Start with adding an output mapping and changing the XPath expression. WebRPC gives you immediate feedback upon every keystroke which makes it very easy to edit the XPath queries correctly and efficiently. If you have trouble finding the proper query expression or if you are new to XPath, simply type the string you are looking for in the search box on the page. WebRPC will try to compute the most efficient and simple XPath query that retrieves the value you are looking for. Feel free to modify the computed query later on to further refine your output mapping.

Code

The code generation page is the central page to use when all inputs and outputs have been specified. The supported languages are VB.NET, C#, Java, JavaScript, and PHP. Further language specific options, such as an online check of the JavaScript code or adding proxy support for Java, are available once the target language has been chosen.

Workflow

The workflow page is basically a specialized search page focusing on finding services that can be called with the current service's outputs or services that can provide inputs for the current service. For instance, a geocode service that provides longitude and latitude information given an address can provide the inputs for a weather service which needs longitude and latitude inputs. The composite service will then be able to provide weather information for a given address.

Performance

The performance page provides you with an overview of the service performance and availability. Measurements are taken every hour. The graphs show the average time and the average failure rate in the interval represented by each graph point. The bottom of the page shows a more detailed report on specific failures and performance data. The category "outputs missing" indicates whether an output mapping was specified but the value was not present in the result. This is an indicator for changes in the service's behavior (e.g. data that was present before is now missing).

Rating

Once you are logged in, you can rate a service by providing one to five stars and a comment explaining your rating.

Licensing and product versions

www.webrpc.com

The online version of WebRPC is free and offers the full set of features except for saving HTML services. This has legal reasons, since most HTML pages do not allow scraping the contents programmatically. Therefore, saving and monitoring HTML services is disallowed. The client code is available under the GNU General Public License Version 2, June 1991

www.webrpc.com

The Intranet version comes with an SDK and allows you to access internal services and also supports saving and monitoring of HTML services. The client code is available under the WebRPC commercial license.

User Management

The requirement for signing up is simply a valid email address. Your email address is not displayed to other users. Services you create are tagged with your display name only.