REST Web Service Resources
What
is a REST web service resource?
Creating
a REST web service resource
Rest web service resource toolbar
Using
the REST web service resource
Adding
the resource to the form
Mapping
rest web service resource fields to form fields
Calling
REST web service resource
Testing the REST web service resource
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:
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.
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.
Resource
Description allows you to provide a description for this resource.
Target
Base URI specifies the base URI for
the target server.
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.
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:
e.g.
POST
http://myresource.com/customers/&&customerId
&&requestBody
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.
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:
e.g.
HTTP/1.1 200 OK
accessCode : &&accessCode
&&responseBody
Security can be configured separately for each endpoint. Click the icon on the endpoint toolbar.
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.
Right click the endpoints tree node in the REST web service resource tree panel and select Delete.
Right click
the endpoints
tree node in the REST web
service resource tree panel and select Rename.
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.
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.
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.
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
Save: saves the email resource.
Maintain Documentation
Show information: dates for creation, last update and import of this REST Resource.
Shows this help page.
Add the REST Web Service Resource to the Resources
View in the form.
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.
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. |
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.