Automatically Generated Resources

Table of Contents

Just by virtue of deploying the service, the WSO2 mashup server generates a number of descriptive artifacts and tools to make it easy to consume the web service you've just created. These artifacts are linked from the mashup page which can be accessed via the management console, or can be accessed directly from the endpoint URI associated with the service. Typically the endpoint URI is http://{host ip}:9763/services/{service name}, where the service name is by default the name of the JavaScript file defining the service (minus the '.js'). By appending one of the following queries to the endpoint URI, different artifacts and tools can be accessed:
?wsdl2 WSDL 2.0 description of the service
?wsdl WSDL 1.1 description of the service
?xsd XML Schema description of the service
?stub JavaScript or E4X stub for accessing the service
?tryit Ajax client for simple, generic interactions with the service
?gadget A custom gadget (if there is one) for the service, currently only Google gadgets are supported
?source The JavaScript source code for the service
?template A source code template for developing a custom UI
?doc Documentation for the service

WSDL (?wsdl2, ?wsdl)

By appending '?wsdl2' to the endpoint URI, you can retrieve an automatically-generated WSDL 2.0 document describing the service. For the helloworld service, try http://<your-machine-ip>:9763/service/helloworld?wsdl2. The WSDL describes the operations the service exposes, the structure of the XML that is sent and received by each operation, and how to communicate with the service to retrieve the XML content. By default, six different types of endpoints are deployed. Each of these endpoint types are represented by the WSDL 2.0 <endpoint> elements of the service, and by the <binding> elements which these endpoints refer to. The default six types of endpoints are:
  1. SOAP 1.2 over HTTP
  2. SOAP 1.1 over HTTP
  3. Plain old XML/REST over HTTP
  4. SOAP 1.2 over HTTPS
  5. SOAP 1.1 over HTTPS
  6. Plain old XML/REST over HTTPS
One can also get a WSDL 1.1 description of the service by appending '?wsdl' to the endpoint URI. For the helloworld service, try http://<your-machine-ip>:9763/service/helloworld?wsdl. For more information on precisely how the Mashup Server generates WSDL, see JavaScript Annotations.

XML Schema (?xsd)

Although accessing '?wsdl' or '?wsdl2' gives you a service description that includes an XML Schema description of the XML structure, you can also ask for the XML Schema separately using the '?xsd' option. For the helloworld service, try http://<your-machine-ip>:9763/services/helloworld?xsd.

JavaScript Stubs (?stub)

Most Web Service toolkits can successfully use the WSDL description to provide a nice programming model for accessing the service. For instance, WSO2 Web Services Application Server (WSAS) provides a utility wsdl2java which generates Java code for interacting with the service in a manner friendly to Java programmers. Similarly, the Mashup Server provides a tool for interacting with a service in a manner friendly to JavaScript programmers. The '?stub' option returns a JavaScript file that can be included in a Web page or another mashup service to make interacting with the service easy and natural. For example, if a web page is to interact with the hello world service, you only have to include the stub and you can use the WSRequest object -- available natively in the Mashup Server, or a simple version in native JavaScript (shown below) -- to call the Web service simply and naturally. Please refer Writing a Helloworld client for further details. The '?stub' option accepts these additional parameters:
  • lang: Whether the stub should use native E4X XML datatypes, or use DOM to represent XML. The value 'e4x' indicates that native E4X datatypes should be used, the values 'js', 'ecmascript', and 'javascript' are synonymous terms for indicating that XML should be exposed through the DOM.
  • service: When a WSDL 2.0 document from which the stub is generated contains more than one <service> element, this parameter can be used to select which service to build a stub for. By default the first <service> is used. When writing services in JavaScript, each file corresponds to a single service.
  • localhost: When set to true returns a stub that has the endpoint reference as localhost instead of using an IP. Optimum for a Mashup hosted on this server (especially for including).
For more information on using stubs, especially on using them asynchronously, see Using Stubs.

Try-it (?tryit)

The first thing you might want to do with your new service is try it out. The '?tryit' option provides a quick and easy way to exercise the service right out of the box. The try-it window for a service might look something like this: try it

You can choose the operation you'd like to invoke from the list on the left hand side, fill in the necessary parameters, and invoke the operation to view the result. If you need more typing space (for instance, the parameter takes a blob of XML) you can expand the size of the input field by clicking on the small icon in the lower right corner of each field. A few notes about the Try-it page:
  • The documentation from the documentation annotation is displayed, and good documentation makes the try-it much nicer to use. I hope this encourages you to use the available documentation facilities!
  • The input fields for the parameters initially show the XML Schema type of data that's expected. 'anyType' means an XML element. Note that you are responsible for keeping the XML for these types of services well-formed. You can also get this information from the tooltip.
  • The try-it page is a full Ajax client and interacts with the service just as any other client would, so it's a good way to verify that a service not only works, but is reachable by the clients. Note however that the try-it page attempts to contact the Web Service at the endpoint url provided. If the domain or url scheme of the service are different than the endpoint, the browser may impose security restrictions. In this case the try-it falls back to using a script-injection protocol to tunnel the web service request. In this case, a wire trace of the communication with the browser will not show the actual web service messages used to communicate with the service.
  • The try-it page can dynamically switch between the available endpoints using the expand to change link. You can choose an appropriate endpoint, manually edit the endpoint address if necessary (e.g., to redirect messages throughtcpmon), and if appropriate link to an alternate try-it that makes more endpoints available (when the try-it page is served up under HTTP, only HTTP endpoints appear, but if you get the try-it page from HTTPS, then HTTPS endpoints may appear instead.). The current endpoint is used is displayed on the top left corner of the page.
  • When you have selected a Plain Old XML/REST binding such as HTTP or HTTPS, and the operation you are invoking is annotated as "safe", the try-it will provide a link to the service. As you enter values into the form, they will appear in the link. You can click on this link to see the operation results directly in the browser, or copy it into code that accesses the Web service directly through HTTP.
  • If the service is secured using a username/password security scenario, the try-it will display username and password fields. Security scenarios other than usename/password authentication are not supported at this time.
  • The try-it page is fully asynchronous, so it doesn't block while a Web service is being invoked. You could invoke several operations before one of them completes (though it doesn't have a way to see the results of the same operation invoked multiple times.)
Feel free to take the Try-it as the basis for a custom Ajax-style Web application to interact with your service. You'll find the source code quite minimal.

Gadget (?gadget)

A version of the try-it packaged as a Google gadget. Copy the URL into your Google gadget host (the Mashup Server Dashboard or a host like iGoogle) to access the try-it for the service as a gadget. Note that the Mashup Server must be internet accessible for the gadget to work in a service such as iGoogle.

Source Code (?source)

The source code for a service can be accessed through the '?source' option. By default, the source code is available for each service, but in a future release, we will allow you to prevent others from viewing, copying, adapting, or even fixing your code with an option in the administrative console.

Source Code Templates (?template)

A template for a custom UI can be obtained with the '?template' option. This provides a convenient starting place for writing a custom UI in HTML or as a Google Gadget. The template gives minimal functionality to call the mashup Web service, and will work out of the box for many services. Other services will require some service-specific coding before they begin to work. For instance, a service may require operations to be called in a specific order, or the types of inputs allowed may be restricted further than is described in the schema (e.g. an xs:string type may have to be a valid US city name.) The '?template' option requires an additional parameter:
  • flavor: The type of template to generate. Supported values are 'html' for an HTML Ajax application, or 'googlegadget' for a Google Gadget manifest suitable for hosting in the Dashboard or an external Google gadget host such as iGoogle.

API Documentation (?doc)

The documentation for a service, as defined in by the 'documentation' annotations, can be accessed with the '?doc' query. The returned HTML format is intended for reference, printout, etc.