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