Cloud Software Group, Inc. EBX®

Documentation > Developer Guide > EBX® Script > Usage

Navigation modeDocumentation > Developer Guide > EBX® Script > Usage

REST service

Introduction
Configuration and authentication
Calling a REST service

Introduction

EBX® Script can call external REST services using the HTTP API . This API provides methods to:

Create HTTP requests.
Add parameters to headers.
Read responses (message body, HTTP code, etc.)

Use the following HTTP methods to perform operations on server resources:

GET : retrieves a resource or a collection from the server.
POST : sends data to create a new resource on the server.
PUT : sends data to update an existing resource on the server.
DELETE : deletes a resource on the server.

REST services can be called from table triggers and script tasks using the EBX® Script IDE.

Configuration and authentication

Configure each REST service called in a script in the following table : Administration > Integration > External services > Configuration where the following properties are required:

Configuration id : The unique identifier for the REST configuration. It is required to create an HTTP request in the API.
Base URL : The URL of the server to call. Use HTTPS to encrypt the communication between the client and the server. The URL has the following format:

  http[s]://<host>[:<port>]/{path}{?<queryParameters>}

  where

  - host and port: defines the server address where the API resides.
  - path: is the path of the specific resource within the API.
  - queryParameters: are optional parameters used to filter or refine the resource.

Usage : Defines how the service is used: AI Assistant and/or the REST service.
Authentication type : Specifies the authentication type used to access resources. The following types are supported:

Type	Description
Basic	is a simple and fast method of HTTP authentication that requires a valid username and password. Credentials are encoded in base 64 and included in the HTTP request header. Note that there is no need to add the authentication code in the header of the request. It is automatically included before each access to the server.
EBX	enables access to the EBX Built-in RESTful service. A valid username and password must be provided to obtain an authentication token. The token has a timeout period. A new token is requested and included in the HTTP request header for each access to the EBX® server. Note that there is no need to add the EBX token in the header from the script. It is automatically included before each access to the EBX® server.
Custom	enables custom authentication by providing valid key names and key values. The values of the keys can be secret and are encrypted based on the keystore. This custom type can be used to call a service with authentication like API keys, tokens, or OAuth.
None	no authentication is needed.

Calling a REST service

To call a REST service from an EBX® script:

Navigate to Administration > Integration > External services > Configuration and configure the server: set a configuration ID, URL, authentication type, and credentials.
Access table triggers or script tasks within the EBX® Script IDE.
Call the REST service using the specified configuration ID.

Create a request

A new HTTP request can be created using the core.http API. It provides methods to configure the request, add paths, parameters and header fields.

The following examples show some scripts calling a REST service.

Example : create a request to get all products of a specific category

GET https://api.example.com/v1/products/?sort=desc&category=jewelery

The following configuration is used:

configuration id: ebx-1
URL: https://api.example.com
Usage: Rest
authentication type: basic
credentials: username, password

uses core.http as client;
...
procedure getJeweleryProducts()
begin

  // create a request with basic authentication
  var request := client.createRequest('ebx-1');

  // include content type in the header
  client.setHeader(request,'Content-Type','application/json');

  // add paths
  client.addPath(request,'v1');
  client.addPath(request,'products');

  // add query parameters
  client.addParameter(request,'category','jewelery');
  client.addParameter(request,'sort','desc');
  ...
  // sends a request to get products of a specific category
  ...
end

Example : create a request to get all products with a limited result.

GET https://api.example.com/v1/products?limit=15

The following configuration is used:

configuration id: ebx-2
URL: https://api.example.com
Usage: Rest
authentication type: custom
key name: api_key
key value: access_key

uses core.http as client;
...
procedure getProducts()
begin
  // create a request with custom authentication
  var request := client.createRequest('ebx-2');
  client.addPath(request,'v1');
  client.addPath(request,'products');
  client.addParameter(request,'limit','15');

  // get api_key value saved during the configuration of the REST service
  var accessKey := client.getConfigValue(request,'api_key');
  if not isNull(accessKey) then
  begin
    // include the authorization api_key in the header
    client.setHeader(request,'Authorization','api_key '| accessKey);
    ...
    // sends a request to get all products
    ...
  end
end

Example : create a request to call the EBX Built-in RESTful service and update the user email.

PUT https://ebx-example.io/test/ebx-dataservices/rest/data/v1/Bdataspace/dataset/root/user/ID6766

The following configuration is used:

configuration id: ebx-3
URL: https://ebx-example.io/test/ebx-dataservices
Usage: Rest
authentication type: ebx
credentials: username, password

uses core.http as client;
...
procedure updateUserEmail()
begin

var request:= client.createRequest('ebx-3');

// add paths
client.addPath(request,'data/v1/Bdataspace/dataset/root/user/ID6766');

// include the content type in the header
client.setHeader(request,'Content-Type','application/json');

// sends a put request to update the user email
...
end

Example : create a request to get information about a city

GET https://geo.api.gouv.fr/communes?codePostal=92160&fields=nom,departement,region

The following configuration is used:

configuration id: ebx-4
URL: https://geo.api.gouv.fr/communes
Usage: Rest
authentication type: none

uses core.http as client;
...
procedure getCityInfo()
begin

   var request:= client.createRequest('ebx-4);

   // add query parameters
   client.addParameter(request,'codePostal','92160');
   client.addParameter(request,'fields','nom,departement,region');

   // get the url of the request.
   var message:='Request URL : '|client.getRequestUrl(request);

   // sends a request to get information about a city specified by its zipcode 92160
   ...
end

Send a request

The core.http API provides several HTTP methods (GET, PUT, POST, DELETE) to call a REST service. The following examples show some scripts using HTTP method to perform operations on the products.

GET

Example : retrieve a single product from the server

GET https://api.example.com/v1/products/P87RZ63

The following script sends a GET request to retrieve a single product by its identifier.

uses core.http as client;

procedure getSingleProduct()
begin
  var request := client.createRequest('ebx-1');
  client.addPath(request,'v1/products/P87RZ63');

  // get response
  var response := client.get(request);
  ...
end

POST

Example : create a new product on the server

POST https://api.example.com/v1/products

The following script sends a POST request to add new product.

uses core.http as client;

procedure addProduct()
begin
  var request := client.createRequest('ebx-1');
  client.addPath(request,'v1/products');
  client.setHeader(request,'Content-Type','application/json');
  var body:='{
                 "id": "L32LQ",
                 "title": "TV LED Sony",
                 "price": 1543,
                 "image": "https://tv.pravatar.sony",
                 "category": "electronic"
             }';

 // sends a POST request
  var response := client.post(request,body);
  ...
end

PUT

Example : update an existing product on the server.

PUT https://api.example.com/v1/products/L32LQ

The following script sends a PUT request to update a specific product.

uses core.http as client;
...
procedure updateProduct()
begin
  var request := client.createRequest('ebx-1');
  client.addPath(request,'v1/products/L32LQ');

  var body:='{
                 "price": 789
             }';

 // sends a PUT request
  var response := client.put(request,body);
  ...
end

DELETE

Example : deletes an existing product on the server.

DELETE https://api.example.com/v1/products/L32LQ

The following script sends a DELETE request to delete a specific product.

uses core.http as client;
...
procedure deleteProduct()
begin
  var request := client.createRequest('ebx-1');
  client.addPath(request,'v1/products/L32LQ');
  var response := client.delete(request);
  ...
end

Read a response

Use the core.http API to read status codes, headers, and bodies of the response. Use json.http to parse the response body and manage JSON data.

Example : read the body response of the request to get information about a specific product.

uses core.http as client;
uses core.json as json;
uses core.log as log;
...
procedure getProductInfo()
begin
  var request := client.createRequest('ebx-1');
  client.addPath(request,'v1/products/P87RZ63');

  // send a get request
  var response := client.get(request);

  // get status code of the response
  var status:=client.getStatusCode(response);
  if (status = 200) then
  begin

     if (client.hasBody(response)) then
     begin
       // get the first content encoding from the response header
       var encoding := client.getHeaderFirstValue(response,'content-encoding');

       // get the list of access allowed methods from the response header
       var allowedMethod := client.getHeaderValues(response,'access-control-allow-methods');

       // get the body of the response as object
       var body:=client.getJsonBody(response).asObject;

       // retrieve information about the product
       log.info('id :' | json.getString(body ,'id'));
       log.info('title :' | json.getString(body ,'title'));
       log.info('price :' | json.getString(body ,'price'));
     end
    ...
  end
end

Handle response errors

When an error occurs, check the status code and the additional information reported in the response body. The core.http API provides methods to fetch the request URL, to get the status code, and to read error messages in the response body.

Example : log response errors when sending a request to the EBX Built-in RESTful service to update the user email.

uses core.http as client;
uses core.json as json;
uses core.log as log;
...
procedure updateEmail()
begin

   var request:= client.createRequest('ebx-3');
   client.addPath(request,'data/v1/Bdataspace/dataset/root/user/ID66Z7');

   // set a new timeout for the request
   client.setTimeout(request,800);

   var json:='{
                   "content": {

                     "email": {
                       "content": "loana-provost@gmail.com"
                     }
                   }
              }';

    // update user email
    var response := client.put(request,json);
    var status:=client.getStatusCode(response);

   // read the response
   if (status>=200 and status <=300) then
    begin
       log.info('The request was successful '|status);
      if (client.hasBody(response)) then
      begin
        log.info('Response body: ' | client.getStringBody(response));
      end
    end
   else
      begin
        log.info('Error when sending the request');
        // log the url of the request.
        log.info('Request URL : '|client.getRequestUrl(request));

        // log the url of the response.
        log.info('Response URL : '|client.getResponseUrl(response));

        var body:=client.getJsonBody(response).asObject;
        // log error status code
        log.info('Code : ' | json.getDecimal(body,'code'));

        // log error message
        var errors:=json.getArray(body,'errors');
        for error in errors do
         begin
         log.info('Message : ' |  json.getString(error.asObject,'message'));
         end
      end
end

Documentation > Developer Guide > EBX® Script > Usage

TIBCO EBX® Version 6.2.2. Copyright © 2001-2025. Cloud Software Group, Inc. All rights reserved.

All third party product and company names and third party marks mentioned in this document are the property of their respective owners and are mentioned for identification.