REST Web Service Resources

Documentation home

 

What is a REST web service resource? 1

Creating a REST web service resource. 2

General Properties 3

Endpoints 4

Creating an Endpoint 4

Endpoint Request 7

Endpoint Response. 9

Endpoint Security. 10

Multiple Endpoints 10

Deleting an endpoint 10

Renaming an endpoint 10

Endpoint toolbar 11

Endpoint tree panel toolbar 11

Resource Fields 11

Resource fields toolbar 11

Rest web service resource toolbar 11

Using the REST web service resource. 12

Adding the resource to the form. 12

Mapping rest web service resource fields to form fields 12

Calling REST web service resource. 12

Testing the REST web service resource. 13

 

See also: RESTful web services overview, Calling RESTful web service with programming API, RESTful Web Service Tutorial, Configuring Endpoint security, OAuth Authentication, How Resources Work

 

 

There are two techniques that can be used to implement a call to a RESTful web service:

 

                       

What is a REST web service resource?

 

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 resource fields named requestBody, responseBody and 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

 

Response Timeout Time to wait in seconds for a response, once a remote connection has been made. If no response is returned within the configured timeout the REST call generates a timeout error. The default is 60 seconds if no value is specified. Specifying 0, the REST service call will wait indefinitely.

 

Debug When checked, the inbound and outbound REST call request and response information are logged.

 

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. A default resource field of &&requestBody is created when the resource is first created or an endpoint is added.

 

 

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:

 

  1. HTTP Method – e.g GET
  2. 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
  3. Any configured request headers – e.g myCustomHeader : &&customHeader
  4. 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. A default resource field of &&responseBody is created when the resource is first created or an endpoint is added.

 

 

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:

 

  1. HTTP/1.1 200 OK – This is an example response and never changes.
  2. Any configured response headers – e.g accessCode : &&accessCode
  3. 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.