Chapter 5- Web Services, Web Service URLs, and the REST API
| New to 2019! |
| Sharing workspaces has never been easier than in FME Server 2019.0. We have added Web Service URLs and FME Server Apps. FME Server Apps allow a user to run a workspace without having to log into FME Server. Web Service URLs can be used in a third party application. We will discuss how to use Web Service URLs in the second section of this course. |
A Web Service URL looks similar to the REST API Request URL; however, it exists outside of the REST API. A Web Service URL should be used instead of a REST call if you are intending on using the Data Streaming or Data Download Service. A job submitted by a REST call will not have access to these services.
To find an example of the Web Service URL log into FME Server and locate a workspace.
Open the advanced tab and scroll down until you find the Workspace Sharing. Select Workspace Sharing.
Once you have selected that link, you will be asked to create a new token to run that workspace.
In this area you can change the Token Name, Description, and when the Token will expire.
Select OK to create the token.
Click the Web Service URL to run the workspace.
Like the REST API, the Web Service URL can run a job synchronously and asynchronously. The job will automatically run synchronously.
To run the job asynchronously enter an email in the section that says Email results to. By doing this the Web Service URL will automatically be updated to run asynchronously. Once the job has completed an email will be sent.
Just like in the REST API there are parameters you may change in the Web Service URL.
The following table was copied from the following manual on the Data Download Service. For full documentation see the Data Download Service documentation.
Web Service URL Request Parameters
| Name | Value | Description |
|---|---|---|
| opt_responseformat | xml or json Default: xml | The language of the response. The text must be in lowercase |
| opt_geturl | The URL to a dataset | The URL of the source dataset to be used for transformation |
| opt_showresult | true or false | Whether the XML/JSON responses include the FME transformation result. The default value is true if this parameter is not present. |
| opt_servicemode | sync or async or schedule | Toggles between synchronous and asynchronous modes of the service. When jobs are submitted asynchronously (async), the response of submission success or failure is returned immediately. When set to synchronous (sync), the response is not returned until the job completes. Or, schedules a data download request to run at a specified start time (one-time only). If a schedule is specified, see below for additional parameters. |
| opt_requesteremail | Comma separated email addresses | Addresses to which the notification e-mail messages are sent. |
The Web Service URL and REST API can be combined together in an application to utilize the best components of both. An example is in the Easy Translator demo.
Files are uploaded with the REST API; however, the job is run using a Web Service URL.
This is a section of code for the dataUpload function from the FME REST API JavaScript Library. Please note it is not the full function but should provide some context to how the calls look like in a JavaScript function.
dataUpload : function(repository, workspace, files, jsid, callback) {
var url = buildURL('{{svr}}/fmedataupload/' + repository + '/' + workspace);
var token = getConfig('token');
url = url + '?token=' + token;
ajax(url, callback, 'POST', params);
The URL is built with the with the call we see in the REST API, then the token is added to the end of the URL. The URL is submitted with the POST method.
Luckily, this call and almost all of the calls within the FME Server REST API exist within the REST API JavaScript library, so the user does not have to write the functions. A user can successfully create an application by simply calling the functions already created.
The Web Service URL used in a JavaScript function would look like this:
var submitUrl = BuildForm.host + '/fmedatadownload/' + BuildForm.repository + '/' + BuildForm.workspaceName + '?SourceDataset_GENERIC=' + files;
submitUrl = submitUrl + '&SourceFormat=' + sourceFormat;
submitUrl = submitUrl + '&DestinationFormat=' + destFormat;
submitUrl = submitUrl + '&COORDSYS_Dest=' + outputCoordSys + '&opt_responseformat=json';
Here the Web Service URL is built, then the user would click the DirectURL to activate it.