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. |