- Introduction to WorkXpress
- Building Your Application
- Examples and Best Practices
- Technical Manual
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.
There is currently only one data handler available for this data source.