Package com.ebasetech.xi.api.connectors

Interface RESTDataConnector

All Superinterfaces:
java.io.Serializable
public interface RESTDataConnector
extends java.io.Serializable
RESTDataConnector provides integration with a non-UI, external data service, for example a REST Service.

A Data Connector is a Server Side JavaScript entity that provides the following functionality:

  • A pure JavaScript API to communicate to a specific REST service such as a third-party API.
  • Direct communication with a REST service without having to call RestServices API helper methods.
  • Methods and definitions for interacting with the REST service.

A new Data Connector is automatically added to the one of following namespaces:

  • connectors.verjio.<connectorname> - When the Data Connector is downloaded from the Verj.io Resource Hub.
  • connectors.dataconnectors.<connectorname> - When a new Data Connector is created in your workspace.

The HTTP header Content-Type: application/json is set as default. This can be overridden by calling the RESTDataConnector#setDefaultHeader(String, Object) function.

A Data Connector contains custom JavaScript functions used to call the remote service directly. These functions should be appropriately named to reflect the intention of the call, for example:

JavaScript example: Data Connector functions 

  function ExampleWeatherStation(stationId) {
     const restDataConnector = connectors.createRESTDataConnector("https://weather.example.com/api/");

     // Set the station identifier as a header for all requests
     restDataConnector.setDefaultHeader('station', stationId);
   
     // Submit a weather station temperature reading
     // Defaults to centigrade ("c") for the units
     this.submitTemperatureReading = function (temperature, unit) {
        const uri = restDataConnector.createUri("submit/temperature");
        const body = {
             temp: temperature,
             unit: unit || 'c',
        };
        return restDataConnector.post(uri, body);
     }
  }
The DataConnectors properties should be configured using the Verj.io Server Administration Console, for example an API key or application identifier. JavaScript example: Creating a new data connector. 
  // Get the "ExampleWeatherStation" Data Connector configuration from the server
  
  function ExampleWeatherStation(stationId) {
     const restDataConnector = connectors.createRESTDataConnector("https://weather.example.com/api/");

     // Get the configuration
     const config = connectors.getConfig("ExampleWeatherStation");

     // Use the stationId parameter or fall back to the value configured on the server
     // The double underscore prefix indicates that the variable is internal to the Data Connector
     const __stationId = stationId || config.stationId; 

     // Set the station identifier as a header for all requests
     restDataConnector.setDefaultHeader('station', __stationId);
  }
The DataConnectors is added to the Form and it can be accessed via a server side JavaScript event, for example a Button Control onClick event.

JavaScript example: button click event 

  // The ExampleWeatherStation Data Connector is available in the connectors.dataconnectors namespace
  try {
     connectors.dataconnectors.ExampleWeatherStation.submitTemperatureReading(22);
  } catch (e) {
     log(`Error submitting temperature reading: ${e}`);
     event.owner.addErrorMessage('Unable to submit temperature reading.');
  }

  event.owner.addInfoMessage('Temperature reading submitted successfully!');
Further documentation
Since:
V5.13

  • Method Summary

    Modifier and Type Method Description
    java.lang.String createUri​(java.lang.String endpoint)
    Returns a URI to the specified endpoint in the API.
    java.lang.Object delete​(java.lang.String uri)
    Performs an authenticated DELETE request to the API using the settings of the RESTDataConnector
    java.lang.Object delete​(java.lang.String uri, java.util.Map<java.lang.String,​java.lang.Object> options)
    Performs an authenticated DELETE request to the API using the settings of the RESTDataConnector The default headers from the RESTDataConnector are included in the request.
    java.lang.Object get​(java.lang.String uri)
    Performs an authenticated GET request to the API using the settings of the RESTDataConnector
    java.lang.Object get​(java.lang.String uri, java.util.Map<java.lang.String,​java.lang.Object> options)
    Performs an authenticated GET request to the API using the settings of the RESTDataConnector The default headers from the RESTDataConnector are included in the request.
    Authentication getDefaultAuthentication()
    Returns the Data Connector's default HTTP authentication
    java.lang.Object getDefaultHeader​(java.lang.String header)
    Returns the default header value for a given name.
    java.util.Map<java.lang.String,​java.lang.Object> getDefaultHeaders()
    Returns the default headers object for API calls.
    java.lang.Object head​(java.lang.String uri)
    Performs an authenticated HEAD request to the API using the settings of the RESTDataConnector
    java.lang.Object head​(java.lang.String uri, java.util.Map<java.lang.String,​java.lang.Object> options)
    Performs an authenticated HEAD request to the API using the settings of the RESTDataConnector The default headers from the RESTDataConnector are included in the request.
    java.lang.Object patch​(java.lang.String uri, java.lang.Object body)
    Performs an authenticated PATCH request to the API using the settings of the RESTDataConnector The request body will be automatically stringified.
    java.lang.Object patch​(java.lang.String uri, java.lang.Object body, java.util.Map<java.lang.String,​java.lang.Object> options)
    Performs an authenticated PATCH request to the API using the settings of the RESTDataConnector The default headers from the RESTDataConnector are included in the request.
    java.lang.Object post​(java.lang.String uri, java.lang.Object body)
    Performs an authenticated POST request to the API using the settings of the RESTDataConnector The request body will be automatically stringified.
    java.lang.Object post​(java.lang.String uri, java.lang.Object body, java.util.Map<java.lang.String,​java.lang.Object> options)
    Performs an authenticated POST request to the API using the settings of the RESTDataConnector The default headers from the RESTDataConnector are included in the request.
    java.lang.Object put​(java.lang.String uri, java.lang.Object body)
    Performs an authenticated PUT request to the API using the settings of the RESTDataConnector The request body will be automatically stringified.
    java.lang.Object put​(java.lang.String uri, java.lang.Object body, java.util.Map<java.lang.String,​java.lang.Object> options)
    Performs an authenticated PUT request to the API using the settings of the RESTDataConnector The default headers from the RESTDataConnector are included in the request.
    java.lang.Object removeDefaultHeader​(java.lang.String header)
    Removes a default header value for a given name.
    void setDefaultAuthentication​(Authentication auth)
    Set the default HTTP authentication for the REST API call
    void setDefaultHeader​(java.lang.String header, java.lang.Object value)
    Set the default header value for a given name.
    void setDefaultHeaders​(java.util.Map<java.lang.String,​java.lang.Object> defaultHeaders)
    Sets the default headers object for a given name for API calls.
    void setErrorHandler​(Function function)
    Override the default error handler for the RestDataConnector.
    void setResponseHandler​(Function function)
    Override the default response hander for the RestDataConnector.

  • Method Details

    • setDefaultHeaders

      void setDefaultHeaders​(java.util.Map<java.lang.String,​java.lang.Object> defaultHeaders)
      Sets the default headers object for a given name for API calls. The headers are always added the Data Connector REST API call

      JavaScript example: 

        var headers = {"Content-Type":"application/json", "Accept":"application/json"};
  restDataConnector.setDefaultHeaders(headers);
      Parameters:
      defaultHeaders - Map of HTTP request headers
      Since:
      v5.13.0
      See Also:
      getDefaultHeaders()

    • getDefaultHeaders

      java.util.Map<java.lang.String,​java.lang.Object> getDefaultHeaders()
      Returns the default headers object for API calls.
      Returns:
      headers object for use with REST requests
      Since:
      v5.13.0
      See Also:
      setDefaultHeaders(Map)

    • setDefaultHeader

      void setDefaultHeader​(java.lang.String header, java.lang.Object value)
      Set the default header value for a given name.

      JavaScript example: 

        restDataConnector.setDefaultHeader("Content-Type", "application/json");
  restDataConnector.setDefaultHeader("Accept", "application/json");
      Parameters:
      header - name
      value - of the header
      Since:
      v5.13.0
      See Also:
      getDefaultHeader(String)

    • getDefaultHeader

      java.lang.Object getDefaultHeader​(java.lang.String header)
      Returns the default header value for a given name.
      Parameters:
      header - name
      Returns:
      header value for the header name or null if not present
      Since:
      v5.13.0
      See Also:
      setDefaultHeader(String, Object)

    • removeDefaultHeader

      java.lang.Object removeDefaultHeader​(java.lang.String header)
      Removes a default header value for a given name.

      JavaScript example: 

        // Remove header
  restDataConnector.removeDefaultHeader("X-Custom-Header");
      Parameters:
      header - name
      Returns:
      header value for the header name or null if not present
      Since:
      v5.13.0
      See Also:
      setDefaultHeader(String, Object)

    • setDefaultAuthentication

      void setDefaultAuthentication​(Authentication auth)
      Set the default HTTP authentication for the REST API call

      JavaScript example: 

        // Create a basic authentication object
  var auth = HttpAuthentication.createBasicAuthentication("username", "password")
  // Set default authentication for the RESTDataConnector
  restDataConnector.setDefaultAuthentication(auth);
      Parameters:
      auth - the default authenticator for the REST API call
      Since:
      v5.13.0
      See Also:
      getDefaultAuthentication(), Authentication

    • getDefaultAuthentication

      Authentication getDefaultAuthentication()
      Returns the Data Connector's default HTTP authentication
      Returns:
      the default authenticator for the REST API call
      Since:
      v5.13.0
      See Also:
      setDefaultAuthentication(Authentication), Authentication

    • createUri

      java.lang.String createUri​(java.lang.String endpoint)
      Returns a URI to the specified endpoint in the API. The URI is a concatenation of the BaseUri and the endpoint

      JavaScript example: 

        // Construct a URL to the endpoint to call. 
  const restDataConnector = connectors.createRESTDataConnector("https://rest.example.com/api/");
  
  const uri = restDataConnector.createUri('endpoint');
  //
     https://rest.example.com/api/endpoint
      Parameters:
      endpoint - path to API endpoint
      Since:
      v5.13.0

    • setResponseHandler

      void setResponseHandler​(Function function)
      Override the default response hander for the RestDataConnector.

      The response handler is a function that handles the RestResponse returned form the RESTFul web service call. This is useful if the response is not JSON based and you want to return your own response object implementation.

      Overriding the response object allows the customisation of response objects regardless of the Data Connector call.

      JavaScript example: 

       // Define a custom response handler
 function handleResponse(response) { 
    var body = JSON.parse(response.getBody());
    return body.data;
 };
 
 var responseHandler = {
    handleResponse: handleResponse,
 };
 restDataConnector.setResponseHandler(responseHandler);
      Parameters:
      function - the Function used to handle the response. Passed the response object as a parameter
      Since:
      v5.13.0

    • setErrorHandler

      void setErrorHandler​(Function function)
      Override the default error handler for the RestDataConnector.

      The error handler is a function that handles the RestResponse returned form the RESTFul web service call when the request is unsuccessful (the HTTP code is not 200). Overriding this function is useful for extracting API-specific response formats and for interpreting error codes.

      Further documentation.

      JavaScript example: 

       // Define a custom error handler
 function handleError(response) { 
    switch(response.code) {
       case 401:
          // Send an email stating that the service is authorized
          fields.unauthorizedError.value = response.body;
          resources.sysAdmin.sendMail();
          throw services.errors.createAuthorisationError("Unauthorized", response.code);
       
       default:
          throw services.errors.createRequestError("Request error", response.code);
    }
 };
 
 restDataConnector.setResponseHandler(handleError);

      Parameters:
      function - the Function used to handle the error. Passed the response object as a parameter
      Since:
      v5.13.0

    • get

      java.lang.Object get​(java.lang.String uri)
      Performs an authenticated GET request to the API using the settings of the RESTDataConnector

      Further documentation.

      JavaScript example: 

       var dc = connectors.createRESTDataConnector('https://myserviceconnector.org/jukebox');
 var response = dc.get(dc.createUri('/playlists'));
 log(response.playlists[0].playlist_name);
      Parameters:
      uri - the URI to call, typically this should use createUri(String) to concatenate the the base URI with the endpoint
      Returns:
      object JSON parsed response body or the original response body if invalid JSON
      Since:
      v5.13.0

    • get

      java.lang.Object get​(java.lang.String uri, java.util.Map<java.lang.String,​java.lang.Object> options)
      Performs an authenticated GET request to the API using the settings of the RESTDataConnector The default headers from the RESTDataConnector are included in the request. Any additional headers, as specified in the second parameter, will be merged.

      Further documentation.

      JavaScript example: 

       var headers = {"Content-Type":"application/json", "Accept":"application/json"};
 var parms = {"customer_id" : 122023};
 var auth = HttpAuthentication.createOAuthAuthentication("connectorauth");
 var opts = new RestOptions();
 opts.setSocketTimeout(60);
 
 var dc = connectors.createRESTDataConnector('https://myserviceconnector.org/customer');
 var response = dc.get(dc.createUri('details'), {headers: headers, parameters: parms,  options: opts, authentication: auth});
 log(response.account_id);
      Parameters:
      uri - the URI to call, typically this should use createUri(String) to concatenate the the base URI with the endpoint
      options - the options object can consist of:
      1. headers: Map of HTTP Headers. These headers will be merged with the data connectors default headers.
      2. parameters: Map of HTTP Parameters.
      3. body: String representation of the HTTP body for the request.
      4. authentication: Authentication object represents the parameters for an authentication request.
      5. options: RestOptions options used to invoke Rest Data Connectors.
      Returns:
      object JSON parsed response body or the original response body if invalid JSON
      Since:
      v5.13.0

    • post

      java.lang.Object post​(java.lang.String uri, java.lang.Object body)
      Performs an authenticated POST request to the API using the settings of the RESTDataConnector The request body will be automatically stringified.

      Further documentation.

      JavaScript example: 

       
  var playlist = {"playlist_name": "My Favourite Songs", "paylist-genre": "rock",
  .....
 var dc = connectors.createRESTDataConnector('https://myserviceconnector.org/jukebox');
 var response = dc.post(dc.createUri('/playlist'), playlist);
 log(response.playlist_id);
      Parameters:
      uri - the URI to call, typically this should use createUri(String) to concatenate the the base URI with the endpoint
      body - a JavaScript object or a native JavaScript type
      Returns:
      the parsed response body or the original response body if invalid JSON
      Since:
      v5.13.0

    • post

      java.lang.Object post​(java.lang.String uri, java.lang.Object body, java.util.Map<java.lang.String,​java.lang.Object> options)
      Performs an authenticated POST request to the API using the settings of the RESTDataConnector The default headers from the RESTDataConnector are included in the request. Any additional headers, as specified by the parameter, will be merged.

      Further documentation.

      JavaScript example: 

        var playlist = {"playlist_name": "My Favourite Songs", "paylist-genre": "rock",
  .....
 var headers = {"Content-Type":"application/json", "Accept":"application/json"};
 var auth = HttpAuthentication.createOAuthAuthentication("connectorauth");
 var opts = new RestOptions();
 opts.setSocketTimeout(60);
                
 var dc = connectors.createRESTDataConnector('https://myserviceconnector.org/jukebox');
 var response = dc.post(dc.createUri('/playlist'), playlist, {headers: headers, options: opts, authentication: auth});
 log(response.playlist_id);
      Parameters:
      uri - the URI to call, typically this should be used createUri(String) to concatenate the the base URI with the endpoint
      body - a JavaScript object or a native JavaScript type
      options - the options object can consist of:
      1. headers: Map of HTTP Headers. These headers will be merged with the data connectors default headers.
      2. parameters: Map of HTTP Parameters.
      3. authentication: Authentication object represents the parameters for an authentication request.
      4. options: RestOptions options used to invoke Rest Data Connectors.
      Returns:
      the parsed response body or the original response body if invalid JSON
      Since:
      v5.13.0

    • put

      java.lang.Object put​(java.lang.String uri, java.lang.Object body)
      Performs an authenticated PUT request to the API using the settings of the RESTDataConnector The request body will be automatically stringified.

      Further documentation.

      JavaScript example: 

       
  var playlist = {"playlist_name": "My Favourite Songs", "paylist-genre": "rock",
  .....
 var dc = connectors.createRESTDataConnector('https://myserviceconnector.org/jukebox');
 var response = dc.put(dc.createUri('/playlist'), playlist);
 log(response.playlist_id);
      Parameters:
      uri - the URI to call, typically this should use createUri(String) to concatenate the the base URI with the endpoint
      body - a JavaScript object or a native JavaScript type
      Returns:
      the parsed response body or the original response body if invalid JSON
      Since:
      v5.13.0

    • put

      java.lang.Object put​(java.lang.String uri, java.lang.Object body, java.util.Map<java.lang.String,​java.lang.Object> options)
      Performs an authenticated PUT request to the API using the settings of the RESTDataConnector The default headers from the RESTDataConnector are included in the request. Any additional headers, as specified by the parameter, will be merged.

      Further documentation.

      JavaScript example: 

        var playlist = {"playlist_name": "My Favourite Songs", "paylist-genre": "rock",
  .....
 var headers = {"Content-Type":"application/json", "Accept":"application/json"};
 var auth = HttpAuthentication.createOAuthAuthentication("connectorauth");
 var opts = new RestOptions();
 opts.setSocketTimeout(60);
                
 var dc = connectors.createRESTDataConnector('https://myserviceconnector.org/jukebox');
 var response = dc.put(dc.createUri('/playlist'), playlist, {headers: headers, options: opts, authentication: auth});
 log(response.playlist_id);
      Parameters:
      uri - the URI to call, typically this should use createUri(String) to concatenate the the base URI with the endpoint
      body - a JavaScript object or a native JavaScript type
      options - - The options object can consist of:
      1. headers: Map of HTTP Headers. These headers will be merged with the data connectors default headers.
      2. parameters: Map of HTTP Parameters.
      3. authentication: Authentication object represents the parameters for an authentication request.
      4. options: RestOptions options used to invoke Rest Data Connectors.
      Returns:
      the parsed response body or the original response body if invalid JSON
      Since:
      v5.13.0

    • patch

      java.lang.Object patch​(java.lang.String uri, java.lang.Object body)
      Performs an authenticated PATCH request to the API using the settings of the RESTDataConnector The request body will be automatically stringified.

      Further documentation.

      JavaScript example: 

       
  var playlist = {"playlist_name": "My Favourite Songs", "paylist-genre": "rock",
  .....
 var dc = connectors.createRESTDataConnector('https://myserviceconnector.org/jukebox');
 var response = dc.patch(dc.createUri('/playlist'), playlist);
 log(response.playlist_id);
      Parameters:
      uri - the URI to call, typically this should use createUri(String) to concatenate the the base URI with the endpoint
      body - a JavaScript object or a native JavaScript type
      Returns:
      the parsed response body or the original response body if invalid JSON
      Since:
      v5.13.0

    • patch

      java.lang.Object patch​(java.lang.String uri, java.lang.Object body, java.util.Map<java.lang.String,​java.lang.Object> options)
      Performs an authenticated PATCH request to the API using the settings of the RESTDataConnector The default headers from the RESTDataConnector are included in the request. Any additional headers, as specified by the parameter, will be merged.

      Further documentation.

      JavaScript example: 

        var playlist = {"playlist_name": "My Favourite Songs", "paylist-genre": "rock",
  .....
 var headers = {"Content-Type":"application/json", "Accept":"application/json"};
 var auth = HttpAuthentication.createOAuthAuthentication("connectorauth");
 var opts = new RestOptions();
 opts.setSocketTimeout(60);
                
 var dc = connectors.createRESTDataConnector('https://myserviceconnector.org/jukebox');
 var response = dc.patch(dc.createUri('/playlist'), playlist, {headers: headers, options: opts, authentication: auth});
 log(response.playlist_id);
      Parameters:
      uri - the URI to call, typically this should use createUri(String) to concatenate the the base URI with the endpoint
      body - a JavaScript object or a native JavaScript type
      options - the options object can consist of:
      1. headers: Map of HTTP Headers. These headers will be merged with the data connectors default headers.
      2. parameters: Map of HTTP Parameters.
      3. authentication: Authentication object represents the parameters for an authentication request.
      4. options: RestOptions options used to invoke Rest Data Connectors.
      Returns:
      the parsed response body or the original response body if invalid JSON
      Since:
      v5.13.0

    • delete

      java.lang.Object delete​(java.lang.String uri)
      Performs an authenticated DELETE request to the API using the settings of the RESTDataConnector

      Further documentation.

      JavaScript example: 

       var dc = connectors.createRESTDataConnector('https://myserviceconnector.org/jukebox');
 var response = dc.delete(dc.createUri('/delete'));
 log(response.result);
      Parameters:
      uri - the URI to call, typically this should use createUri(String) to concatenate the the base URI with the endpoint
      Returns:
      object JSON parsed response body or the original response body if invalid JSON
      Since:
      v5.13.0

    • delete

      java.lang.Object delete​(java.lang.String uri, java.util.Map<java.lang.String,​java.lang.Object> options)
      Performs an authenticated DELETE request to the API using the settings of the RESTDataConnector The default headers from the RESTDataConnector are included in the request. Any additional headers, as specified by the parameter, will be merged.

      Further documentation.

      JavaScript example: 

       var auth = HttpAuthentication.createOAuthAuthentication("connectorauth");
 var opts = new RestOptions();
 opts.setSocketTimeout(60);
 
 var dc = connectors.createRESTDataConnector('https://myserviceconnector.org/customer');
 var response = dc.delete(dc.createUri('delete'), {options:opts, authentication:auth});
 log(response.result);
      Parameters:
      uri - the URI to call, typically this should use createUri(String) to concatenate the the base URI with the endpoint
      options - the options object can consist of:
      1. headers: Map of HTTP Headers. These headers will be merged with the data connectors default headers.
      2. parameters: Map of HTTP Parameters.
      3. body: String representation of the HTTP body for the request.
      4. authentication: Authentication object represents the parameters for an authentication request.
      5. options: RestOptions options used to invoke Rest Data Connectors.
      Returns:
      object JSON parsed response body or the original response body if invalid JSON
      Since:
      v5.13.0

    • head

      java.lang.Object head​(java.lang.String uri)
      Performs an authenticated HEAD request to the API using the settings of the RESTDataConnector

      Further documentation.

      JavaScript example: 

       var dc = connectors.createRESTDataConnector('https://myserviceconnector.org/jukebox');
 var response = dc.head(dc.createUri('/details'));
 ...
      Parameters:
      uri - the URI to call, typically this should use createUri(String) to concatenate the the base URI with the endpoint
      Returns:
      RestResponse returned from the request
      Since:
      v5.13.0

    • head

      java.lang.Object head​(java.lang.String uri, java.util.Map<java.lang.String,​java.lang.Object> options)
      Performs an authenticated HEAD request to the API using the settings of the RESTDataConnector The default headers from the RESTDataConnector are included in the request. Any additional headers, as specified by the parameter, will be merged.

      Further documentation.

      JavaScript example: 

       var auth = HttpAuthentication.createOAuthAuthentication("connectorauth");
 var opts = new RestOptions();
 opts.setSocketTimeout(60);
 
 var dc = connectors.createRESTDataConnector('https://myserviceconnector.org/customer');
 var response = dc.head(dc.createUri('details'), {options:opts, authentication:auth});
 ...
      Parameters:
      uri - the URI to call, typically this should use createUri(String) to concatenate the the base URI with the endpoint
      options - the options object can consist of:
      1. headers: Map of HTTP Headers. These headers will be merged with the data connectors default headers.
      2. parameters: Map of HTTP Parameters.
      3. body: String representation of the HTTP body for the request.
      4. authentication: Authentication object represents the parameters for an authentication request.
      5. options: RestOptions options used to invoke Rest Data Connectors.
      Returns:
      RestResponse returned from the request
      Since:
      v5.13.0