Enterprise Service Bus - Incoming REST Method

The Incoming REST Method ESB gives the software developer the tools to generate an API to access data from a WorkXpress application, add data to a WorkXpress application, or perform a series of actions in a WorkXpress application; the full power of the WorkXpress Actions system is available. This ESB implements a REST based API for external developers to use.

This feature will be available in Platform Version 14.08.976.

The End User, in the context of an API, is an external developer that needs to interact with a WorkXpress application. The exact details of how to interact with the API created via the ESB system will vary depending on the external developer's choice of programming language or library. For example they could be using Dot Net, Java, Ruby, PHP, or even WorkXpress via the Web Service action.

Usually an API is secured so that external developers needs permission before accessing data from an application. When a REST ESB is called the WorkXpress platform begins by running the Authentication trigger on that ESB. This trigger ends when either a WorkXpress API Key or a Manual Authentication Action is executed.

An important part of the authentication process is telling WorkXpress which User it will be operating as. Through use of the API Key Generator you can easily generate an Auth Key that identifies a particular User, and would be used in conjunction with the WorkXpress API Key Action. In addition to the WorkXpress API key system it is possible to develop a custom authentication scheme using evaluations and the Manual Authentication Action, however keep in mind that this Action requires a User be defined. If an open API is required then the manual authentication action can be used without prior evaluations to always automatically allow access, however this should be very rare and is not advised.

Once Authentication is successful the ESB moves on to it's Processing trigger. As with the Authentication Trigger all input parameters are available to the Software Developer through the Runtime Value system in each Expression. Here the Developer writes the actions that make this API Call have meaning. Most external developers are calling the API to get a return of some kind from your system, and you will provide that return with the Return Value Action.

The following is an example of how an external developer using PHP might interact with a WorkXpress application that defined a REST web method called formatTimestamp that expects 2 parameters: a WorkXpress API key as a query string and a timestamp as part of the url.

$api_key = 'YOUR API KEY HERE';
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://myapp.workxpress.com/api/rest/formatTimestamp/'.time().'?key='.$api_key);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 30);
curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 5);

$formated_string = curl_exec($ch);

$respHttpCode = (int) curl_getinfo($ch, CURLINFO_HTTP_CODE);
$curlErrorNum = curl_errno($ch);
curl_close($ch);

There are no supporting elements explicitly required to implement a REST webservice inside a WorkXpress Application. Common elements that are used in a webservice includes Tables and Fields to read data from or to push data to and Actions to perform operations inside the application. For example a REST method called /contactName/contactID would need a table to represent the contacts and two fields one for the contact name to return and one for the contact id to find the record with.

There are up to five configuration options for this ESB profile.

• URL - This is the url that will be called by the end user in their code / application. All rest urls will always start with [application url]/api/rest.
• HTTP Method - This is the http verb used to call this profile. For example it is possible to implement several api calls, utilizing separate ESB profiles, that use the same url but different http verbs to perform different operations. For example /customer/{customer_id} when called using “GET” will return the details of a customer record but calling the same url with a “POST” and customer details in the post will cause the customer record to be updated.
• Expecting Query String / GET Values and Setup Get Values - These options will allow the software developer to create a list of parameters that the method will need to perform its operation. These pieces of data will be made available to the software developer to use in the actions that implement the API call. The end user will include these parameters in the query portion of the uri. This option is valid for all HTTP Methods.
• Expecting POST Values - This option allows the software developer to inform the ESB profile if a POST will be sent. This option is not valid with the “GET” HTTP Method.
• Type of POST and Setup POST Values - These options will allow the software developer to define a POST Input. If a “Text” based post is selected one runtime value will be available. If a “Key / Value” based POST, also referred to as a form encoded, is selected then a list of parameters that the method will need to perform its operation is used.

There is currently only one data handler available for this data source.

• WorkXpress Actions: REST API - This data handler allows the software developer to generate actions to save values on records like the currently logged in user or to create new records and save the values on them. The full power of the actions system is available.