Table of Contents
|?wsdl2||WSDL 2.0 description of the service|
|?wsdl||WSDL 1.1 description of the service|
|?xsd||XML Schema description of 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|
|?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:
- SOAP 1.2 over HTTP
- SOAP 1.1 over HTTP
- Plain old XML/REST over HTTP
- SOAP 1.2 over HTTPS
- SOAP 1.1 over HTTPS
- Plain old XML/REST over HTTPS
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.
- 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).
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:
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.)
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.