Web Services (version 4.5+)

Requires Platform 4.5+

Accessing Web Services

Nexaweb 4.5 provides a data service to provide Nexaweb Applications with access to data from web services.
The web services data service supports Representational State Transfer (REST) and Simple Object Access Protocol (SOAP) requests.

Configuring the Web Services Data Service

The web services data service configuration file, nexaweb-webservices.xml, contains the following sections:

Configuration Section	Description
webServiceDefinitions	Defines the types of web services available through this data service.
webServiceRequests	Lists REST and SOAP requests defined on the server that your application can use by reference to access external data. Note: You can also specify web service requests in the client UI within an embeddedServiceRequest.

webServiceDefinitions

The webServiceDefinitions section includes the following element:

Element	Description
soapServiceDefinition	Defines an ID for the SOAP service, by which serviceRequests can reference this service.

The soapServiceDefinition element includes the following attributes:

Attribute	Element	Description
id	soapServiceDefinition	Specifies an ID by which to identify this service in serviceRequests.
wsdlLocation	soapServiceDefinition	Specifies the location of the wsdl file to use for the SOAP service.

For example:

<webServiceDefinitions>
     <soapServiceDefinition ID = "soap", wsdlLocation="X" > 
     </soapServiceDefinition>
</webServiceDefinitions>

To configure web services, in the webServiceDefinitions section of the nexaweb-webservices.xml file:

Specify an ID for the SOAP service.
Specify the location of the wsdl file for the SOAP service.

webServiceRequests

This section includes each of the REST and SOAP requests that you want defined on the server and to reference in serviceResourceReference elements of dataDefinitionRequests. You can also create REST and SOAP requests in the client UI file inline in an embeddedServiceRequest.

Creating REST Requests

The web service data service type provides support for communicating with web services implemented using REST architecture.
REST uses HTTP and supports the following methods:

Method	Description
DELETE	Deletes the resource at the specified resource location.
GET	Retrieves the resource at the specified resource location.
POST	Adds the passed data to the specified resource location.
PUT	Replaces the resource at the specified location with the passed data.

You specify REST requests using the <restRequest> tag.

The following table describes the <restRequest> tag's attributes and children:

Element	Type	Description	Required/Optional
id	Attribute	Specifies an ID to identify this request when referenced in a serviceResourceReference element of a dataDefinitionRequests or in an embeddedServiceRequest in the client UI file.	Required
method	Attribute	Specifies one of the HTTP methods, listed above, that this request executes, if any.	Optional. If you do not specify a method, the restRequest uses the GET method by default.
url	Child	Specifies the location of the REST resource.	Required
urlParameters	Child	Includes all urlParameters, which specify, in name and value pair format, additional information to send to the REST resource. For example: <urlParameter name="username">JR</urlParameter>	Optional
body	Child	Specifies the content of the body portion of a PUT or POST request.	Optional

Substitutions

You can substitute any value used in a restRequest by replacing the value with an argument passed to the request, a session variable, or by a pre-processor.

For example:

<webServiceRequests>
  <restRequest id="searchFlickrParam">
    <url>http://www.flickr.com/services/rest</url>
    <urlParameters>
      <urlParameter name="method">
          flickr.photos.search
      </urlParameter>
      <urlParameter name="api_key">
          ffdbbd159bdde999cc638c280377a8d1
      </urlParameter>
      <urlParameter name="text">{0}</urlParameter>
      <urlParameter name="per_page">25</urlParameter>
    </urlParameters>
  </restRequest>
</webServiceRequests>

In this example, the restRequest, searchFlickrPara, invokes a GET to the URL, http://www.flickr.com/services/rest with the following additional parameters: method=flickr.photos.search; api_key=ffdbbd159bdde999cc638c280377a8d1; text=a user supplied value; per_page=25.

Creating SOAP Requests

The Web Service data service provides support for communicating with web services using SOAP.
SOAP is an XML-based protocol for accessing web services over HTTP.

You specify SOAP requests using the <soapRequest> tag.

A <soapRequest> contains the following:

The url for locating the web service
An optional header that can contain session and log information
A body section that contains the details of the actual request

The following table describes the <soapRequest> tag's attributes and children:

Element	Type	Description	Required/Optional
id	Attribute	Specifies an ID to identify this request when referenced in a dataRequestDefinition or data request.	Required
endPointAddress	Child	Specifies the URL location of the Web Service to handle this request.	Required
soapActionURI	Child	Specifies the URI of the action that the SOAP request uses.	Optional
header	Child	Specifies the elements that make up the header portion of the SOAP request. Typically added to the request during pre-processing. Attributes: name - A name associated with this element that allows the data service to identify and modify the element during pre-processing. nameSpace - Specifies the name space of the element.	Optional
body	Child	Specifies the elements that make up the body portion of the SOAP request. Attributes: name - A name associated with this element that allows the data service to identify and modify the element during pre-processing. nameSpace - Specifies the name space of the element.	Required

For example:

<soapRequest id="searchFlickrSoap">
  <endPointAddress>
      http://api.flickr.com/services/soap/
  </endPointAddress>
  <body nameSpace="urn:flickr" localName="FlickrRequest"> 
    <bodyElement name="method">flickr.photos.search</bodyElement> 
    <bodyElement name="api_key">
          ffbbd159dde99cc678c193777c2d9
    </bodyElement> 
    <bodyElement name="text">dog</bodyElement> 
    <bodyElement name="per_page">25</bodyElement> 
  </body>
</soapRequest>

In this example, the SOAP message, searchFlickrSoap, goes to the webservice on the server specified by the URL: http://www.flickr.com/services/soap. urn:flickr is the default namespace for the SOAP request, with a localName of FlickrRequest. The body of the message contains the namespace specific method, flickr.photos.search and specifies an api_key, text, and the number of results per page.

Using Web Services Requests in a Service Request

You can specify a web services request to use in a serviceRequest in any of the following ways:

Location	Description
nexaweb-webservices.xml	Specify a web service request in the webServiceRequests section of the server side nexaweb-webservice.xml configuration file. Then reference it in a serviceResourceReference of a dataRequestDefinition in the nexaweb-data.xml file. (Finally, reference the dataRequestDefinition in a serviceRequest in the client UI file.)
nexaweb-data.xml	Specify a web service request in a serviceResourceDefintion of a dataRequestDefinition in the nexaweb-data.xml file. (Then reference the dataRequestDefinition in a serviceRequest in the client UI file.)
Client UI	Specify a a web service request in an embeddedServiceRequest directly in the client UI file.