A REST web service resource represents an interface to consume a RESTful web service. Each REST web service resource contains a base URI and a list of endpoints representing the service. Each endpoint represents a URI path on the server that maps to a particular HTTP call e.g GET /customers - returns a list of customers from the server.

Each REST web service resource contains three sections:

· Properties tree section on the left-hand side of the editor where you select general properties and manage REST endpoints.

· Property selection section on the right-hand side of the editor where you can configure the general properties for the reset service resource or configure a selected endpoint’s properties.

· Resource Fields section which contains a list of substitutable fields. One field is required for each substitutable variable within the REST resource. A build fields icon is supplied to create these resource fields for you once you have completed the endpoint configuration. These fields are then mapped to the form fields to enable the system to perform the dynamic runtime substitution of values. The request body and response body of the endpoint are represented as a single substitutable field and do not have a structure within the resource. Any request or response structure e.g JSON should be processed outside the REST resource.

Creating a REST web service resource

Right click in the studio tree and select New > REST Web Service Resource.

After creating a new REST web service resource a default Endpoint and a resource field named responseStatusCode are created automatically.

General Properties

Resource Description allows you to provide a description for this resource.

Target Base URI specifies the base URI for the target server.

Endpoints

Creating an Endpoint

Right click the endpoints tree node in the REST web service resource tree panel and select Add Endpoint.

Enter a unique name for the endpoint and click OK. It is possible to add an endpoint without a name. This is known as the “default” endpoint for the REST web service resource. The “default” REST web service resource is either an endpoint with no name or the first endpoint under the endpoints tree node. Click here for more information about calling REST web service resources.

Name displays the name of the endpoint. If the endpoint does not have a name the word “<default>” is shown to indicate that this the default endpoint. Click here for information about renaming an endpoint.

Description is used to add a brief description about the endpoint.

Endpoint URI is used to enter the URI path of the endpoint. This path is appended to the end of the Target Base URI field as described in the general properties. All or parts of the endpoint URI can be substituted with form field variables e.g /customers/&&customerId or /accounts/&&bankId/&&accountId. As the path is entered, it is displayed in the HTTP Request Preview.

Method is selected to determine the type of HTTP method call. The method can be one of:

Method	Operation on the server	Description
GET	The HTTP method GET is used to retrieve a resource	This is a read only call and does not send a request body. The request parameters are concatenated onto the end of the path URI as key=value pairs e.g ?username=joe.bloggs&accountId=1234567. Returns the response body and response headers for the resource.
POST	Inserts a new resource or can update an existing resource	Can both send and receive a HTTP body. The HTTP request body is populated from the body field or a combination of request parameters that are sent in the HTTP request body as encoded key value pairs. The body field will override any request parameters in the HTTP body. A POST is not an idempotent method which means that repeating the same call multiple times may result in multiple resources being created on the server. Also the POST does not require a full URL to the resource. e.g http://myrestservice.com/customers - creates a new customer on the server resulting with a new customerId. http://myrestservice.com/customers/1 - updates customer with customerId=1 The response can return a response body and response headers where applicable.
PUT	Inserts a new resource or updates an existing resource	Similar to a POST apart from: This method is known as idempotent, meaning that no matter how many times a PUT is issued to a resource, the result will stay the same. A PUT requires the full URI to the resource. This implies that the client should construct the full URI including an id, even if it does not exist yet. e.g http://myrestservice.com/customers/1 - Creates a new resource with customerId=1 or updates an existing customer. http://myrestservice.com/customers/ - will not work, PUT requires the full URL. The response populates the response body if applicable.
PATCH	Updates an existing resource. This can send partial information regarding the resource.	Same as a POST apart from the request body can contain partial information regarding the resource. e.g http://myrestservice.com/customers/1 { telephone: 09888767543 } Updates customerId=1 telephone number.
DELETE	Deletes a resource	Does not support sending a request body or receiving a response body. Used to delete a resource. This method is idempotent method which means no matter how many times the the URI is called on a resource, the result will be the same.
HEAD	This is the same as a GET apart from it does not return a response body	Returns only the response headers and does not return a response body.
OPTIONS	Used to find the methods accepted by the resource.	Returns a list of operations allowed for the resource: e.g. GET, POST, DELETE

Endpoint Request

Body – The body of the request document. This can be any string representation required by the resource call. This field can be substituted using form field variable e.g &&request.

Request Query Parameters - Represents a list of request query parameters. Depending on the HTTP method these query request parameters are appended to the end of the URI or written as part of the request body. The full request will be shown in the HTTP Request Preview panel.

Adding Request Query Parameters - Click the icon inside the Request Query Parameters panel. This will insert an empty row into the request query parameters table below. Edit the name of the query request parameter by double clicking the table cell under the Name column. Edit the value by double clicking the table cell under the Value column. The Value column can be substituted with a form field parameter e.g &&customerId.

Removing Request Query Parameters - Select row(s) to remove and click the icon.

Request Headers - Represents a list of HTTP headers that will be sent with the request. It is only necessary to add custom HTTP headers if the RESTful web service requires them.

Adding Request Headers - Click the icon inside the Request Headers panel. This will insert an empty row into the request headers table below. Edit the name of the request header by double clicking the table cell under the Name column. Edit the value by double clicking the table cell under the Value column. The Value column can be substituted with a form field parameter e.g &&customerId.

Removing Request Headers - Select row(s) to remove and click the icon.

HTTP Request Preview - Shows a preview of the HTTP request and how it is formatted. The preview shows the entire HTTP message in the following order:

HTTP Method – e.g GET
The full URI to the resource that is made up of Base URI + Endpoint URI + any GET, HEAD or DELETE request query parameters- e.g http://myresource.com/customers/1?name=Fred
Any configured request headers – e.g myCustomHeader : &&customHeader
Either the request body or the request query parameters if the HTTP method is a POST, PATCH or PUT.

e.g.

POST

http://myresource.com/customers/&&customerId

&&requestBody

Endpoint Response

Body – represents the body of the response document. If configured, this should be specified as a substitutable field e.g &&responseBody. Only Http methods GET, POST, PATCH, PUT support a response body. The response body is always loaded into the body field even if the call is unsuccessful i.e. the HTTP response code is not in the 2xx range.

Status Code – represents the HTTP response code returned from the initial HTTP request. A successful code will be in the 2xx range. Typically this will be 200 on most HTTP methods, or 201 for a PUT. A default resource field of &&responseStatusCode is created when the resource is first created or an endpoint is added.

Response Headers - Represents a list of HTTP headers that will be received as part of the response. A response header should only be added if there is a particular header that needs to be mapped to a form field.

Adding Response Headers - Click the icon inside the Response Headers panel. This will insert an empty row into the response headers table below. Edit the name of the request header by double clicking the table cell under the Name column. Edit the value by double clicking the table cell under the Value column. The Value column can be substituted with a form field parameter e.g &&accessCode.

Removing Response Headers - Select row(s) to remove and click the icon.

HTTP Response Preview - Shows a preview of the HTTP request and how it is formatted. The preview shows the entire HTTP message in the following order:

HTTP/1.1 200 OK – This is an example response and never changes.
Any configured response headers – e.g accessCode : &&accessCode
The configured response body.

e.g.

HTTP/1.1 200 OK

accessCode : &&accessCode

&&responseBody

Endpoint Security

Security can be configured separately for each endpoint. Click the icon on the endpoint toolbar.

Multiple Endpoints

It is possible to add more than one endpoint. If an endpoint does not have a name then this is known as the “default” endpoint. All endpoints must have a unique name. Click here for more information about calling REST web service resources.

Deleting an endpoint

Right click the endpoints tree node in the REST web service resource tree panel and select Delete.

Renaming an endpoint

Right click the endpoints tree node in the REST web service resource tree panel and select Rename.

Endpoint toolbar

Open the security dialog for configuring a security authentication, including HTTP Basic Authentication and OAuth Authentication.

Open the testing REST web service resource dialog.

Show this help page.

Endpoint tree panel toolbar

Add an endpoint to the endpoints tree node.

Delete one or more endpoints from the endpoints tree node.

Rename an endpoint.

Sort the endpoints into alphabetical order.

Resource Fields

The fields Type, Length, Dec. digits cannot be changed and are present only for compatibility with other resource types.

If the Required checkbox is ticked, the call script statement will fail unless a value exists for the mapped field.

Resource fields toolbar

Add a resource field

Delete selected resource fields

Build fields: this is a labour saving device to that will create the resource fields for any substitutable variables found in any of the REST web service fields

Rest web service resource toolbar

Save: saves the email resource.

Maintain Documentation

Show information: dates for creation, last update and import of this REST Resource.

Shows this help page.

Using the REST web service resource

Adding the resource to the form

Add the REST Web Service Resource to the Resources View in the form.

Mapping rest web service resource fields to form fields

To create mappings automatically between form fields and a resource fields, import the resource fields into the form using the Import fields from external resource icon on the Fields View toolbar of the form editor. This will create new form fields of the appropriate type and length and will also create the mapping.

To create mappings manually, select the resource in the Resources View then click on the mappings icon on the Resource View toolbar.

Calling REST web service resource

FPL:

API based language (Javascript):

Syntax:

call RWSR 'myEndpointName';

if [$COMMAND_STATUS = 'OK ']

//call to REST web service successful, write code here

endif

if [$COMMAND_STATUS = 'ERROR']

// call to REST web service failed, write recovery code here

//e.g. show message with mapped response body

message 'Error return from server: ' + RESPONSE_BODY;

endif

Use one of the following methods on RestResource:

try

{

resources.RWSR.call("myEndpointName");

// if the call is successful write code here

// e.g. The resource returns a JSON object

var resultObject = JSON.parse(fields.responseBody.value);

//do something with result object

}

catch (e)

{

if (e.javaException instanceof com.ebasetech.xi.exceptions.RestRuntimeException)

{

log("Error code: " + e.javaException.errorCode);

log("Error reason: " + e.javaException.errorReason);

}

else

{

log(e);

}

// Same example but with the addition of OAuth security authentication

// Firstly authenticate the user

services.security.oauth.authorize("oauthconfigname");

// Then call the web service

try

{

resources.RWSR.call("myEndpointName");

// if the call is successful write code here

// e.g. The resource returns a JSON object

var resultObject = JSON.parse(fields.responseBody.value);

//do something with result object

}

catch (e)

{

// catch errors including authentication failure

if (e.javaException instanceof com.ebasetech.xi.exceptions.RestRuntimeException)

{

log("Error code: " + e.javaException.errorCode);

log("Error reason: " + e.javaException.errorReason);

}

else

{

log(e);

}

See javadoc for further examples.

Testing the REST web service resource

Press the Test Rest Call button to perform a test on the endpoint panel.

The REST call test populates the following:

Description – displays the description as configured in the endpoint.

Endpoint – displays the endpoint URI appended to the base URI.

Method – displays the HTTP method e.g GET, POST etc…

Authentication – displays the authentication method if applicable.

Parameters – Sows a list of substitutable resource fields that are applicable to the request call. These can be configured as part of the Endpoint URI, Request Headers or Query Parameters.

Note that REST calls with OAuth Authorization Code authentication cannot be tested through the test API as this requires user interaction with an external website.

The HTTP Request Preview panel shows a preview of the target URI, request headers and parameters that will be called with the parameters substituted with their configured values.

To test the REST call:

1) Populate any parameter values in the parameters table. Double click the value cell and enter a parameter value. The name column refers to a field listed in the resource fields table.

2) Click the Submit button to perform the test.

3) A dialog will pop up showing the HTTP response from the REST call.

4) Click close to close the HTTP Response dialog.