Skip to main content

Outgoing REST Web Services​

Outgoing REST web services in ADITO enable your application to interact with external RESTful APIs. This allows you to send requests and receive responses from other web services, facilitating integration with third-party systems, data exchange, and automation of workflows.

Overview​

To call external REST web services, use the method net.callRestWebservice. This method requires two parameters:

  • pRestConfig: A REST configuration object created via net.createConfigForRestWebserviceCall(). This object provides setter methods to specify configuration details such as URL, HTTP method, headers, timeouts, and request data.
  • pAuthConfig: An authentication configuration object created using methods from the system.auth JDito module (e.g., auth.createConfigForNoAuth(), auth.createConfigForBasicAuth()). These provide the necessary authentication details for the call.

All available methods and their documentation can be accessed through code completion in your IDE.

Basic Example​

import { net, auth, logging } from "@aditosoftware/jdito-types";

// Create REST configuration and set URL, HTTP method, and timeout
const restConfig = net.createConfigForRestWebserviceCall()
    .url("https://resttest.example.com")  // Set the target URL
    .actionType(net.GET)                   // Set HTTP method explicitly
    .connectionTimeoutInMillis(5000);     // Set connection timeout in milliseconds

// Create authentication configuration with no authentication
const authConfig = auth.createConfigForNoAuth();

// Call the REST web service with the above configurations
const response = net.callRestWebservice(restConfig, authConfig);

// Log the response to see the output
logging.log(response);

Calling REST Web Services with Input Data​

Passing Data via inputValues​

You can pass data to the RESTful web service using input variables bundled in an object, which is then set as the requestEntity in the REST configuration.

import { net, auth, util, logging, question } from "@aditosoftware/jdito-types";

const url = "http://172.23.42.137:8000/webservicecall";     // Target URL for the web service
const actionType = net.POST;                                 // HTTP POST method

const txtmsg = ["This is a test"];                           // Sample data to send

const inputValues = {};
inputValues["AditoData"] = txtmsg;                           // Wrap data in inputValues object

const dataTypeAccept = "text/xml";                           // Expected response data type
const dataTypeSend = "text/xml";                             // Content type of sent data
const dataTypeJDitoAccept = util.DATA_TEXT;                  // JDito data type for accepted data

logging.log("**** Offer: BEFORE calling webservice!");

// Create REST configuration and set all required parameters explicitly
const restConfig = net.createConfigForRestWebserviceCall()
    .url(url)                                                // Set the URL
    .actionType(actionType)                                  // Set HTTP method explicitly
    .dataTypeAccept(dataTypeAccept)                          // Set expected response data type
    .dataTypeSend(dataTypeSend)                              // Set content type of request
    .dataTypeJDitoAccept(dataTypeJDitoAccept)                // Set JDito accept data type
    .requestEntity(inputValues)                              // Set inputValues as request entity
    .connectionTimeoutInMillis(5000);                        // Set connection timeout

// Create authentication configuration with no authentication
const authConfig = auth.createConfigForNoAuth();

// Call the REST web service
const response = net.callRestWebservice(restConfig, authConfig);

question.showMessage("Data passed.");

logging.log("**** Offer: AFTER calling web service! Answer: " + response);

Passing Data via requestEntity (Message Body)​

If you need to send raw data or structured content as the message body, use the requestEntity property to pass the data directly.

tip

Use inputValues when sending structured key-value data that maps to query parameters or form-like objects. Use requestEntity to send raw data (e.g., XML, JSON strings) as the request body.

Simple Example​

import { net, auth, util } from "@aditosoftware/jdito-types";

const requestData = "<resource><ID>4242</ID><NAME>Franz</NAME><PRICE>23</PRICE></resource>"; // Raw XML data to send

// Create REST configuration and set all required parameters explicitly
const restConfig = net.createConfigForRestWebserviceCall()
    .url("http://www.thomas-bayer.com/sqlrest/PRODUCT/")   // Set target URL
    .actionType(net.POST)                                  // Set HTTP method explicitly
    .dataTypeAccept("text/plain")                          // Expected response data type
    .dataTypeSend("text/plain")                            // Content type of request
    .dataTypeJDitoAccept(util.DATA_TEXT)                   // JDito accept data type
    .dataTypeJDitoSend(util.DATA_TEXT)                     // JDito send data type
    .requestEntity(requestData);                           // Set raw data as request entity

// Create authentication configuration with no authentication
const authConfig = auth.createConfigForNoAuth();

// Call the REST web service
const response = net.callRestWebservice(restConfig, authConfig);

Complex Example with JSON Payload and Basic Authentication​

import { net, auth, util, logging } from "@aditosoftware/jdito-types";

const webserviceURL = "https://webservice.tourenplaner.biz/startjob"; // Target URL
const actionType = net.POST;                                           // HTTP POST method

// JSON payload with waypoints data
const requestData = {
    waypoints: [
        {
            address: {
                locality: "Geisenhausen",
                postcode: "84144",
                street: "Konrad-Zuse-Straße 4"
            }
        },
        {
            address: {
                locality: "Landshut",
                postcode: "84028",
                street: "Altstadt 1"
            }
        }
    ]
};

// Create REST configuration and set all required parameters explicitly
const restConfig = net.createConfigForRestWebserviceCall()
    .url(webserviceURL)                                    // Set the URL
    .actionType(actionType)                                // Set HTTP method explicitly
    .dataTypeAccept("application/json")                    // Expected response data type
    .dataTypeSend("application/json")                      // Content type of request
    .dataTypeJDitoAccept(util.DATA_TEXT)                   // JDito accept data type
    .dataTypeJDitoSend(util.DATA_TEXT)                     // JDito send data type
    .requestEntity(JSON.stringify(requestData));          // Set JSON string as request entity

// Create authentication configuration with basic authentication
const authConfig = auth.createConfigForBasicAuth()
    .userName("special@user.de")                           // Set username
    .password("hurgaburga");                               // Set password

logging.log("**** BEFORE calling webservice!");

try {
    // Call the REST web service
    const response = net.callRestWebservice(restConfig, authConfig);
    logging.log("**** AFTER calling web service! Answer: " + response);
} catch (err) {
    logging.log(err);
}

Legacy Methods​

Deprecated Methods

The following legacy methods are still supported for backward compatibility but are deprecated and should be avoided in new development:

  • net.callRestWebserviceNoAuth
  • net.callRestWebserviceBasicAuth
  • net.callRestWebserviceOAuth
  • net.callRestWebserviceOAuth2

Known Issues​

warning

Credentials passed to net.callRestWebserviceBasicAuth must not contain the character ?.

Extended Response JSON Structure​

As of ADITO version 2019.1.3, these legacy methods support an additional boolean parameter pReturnExtendedResponseInfos. When set to true, the response is returned as a JSON object containing extended information about the HTTP response. In the new REST configuration builder, this can be enabled using the setter method .returnExtendedResponseInfos(true).

Possible values:

  • true: Response returned as a detailed JSON object.
  • false: Response returned as a simple string.

When extended response information is enabled, the returned JSON object has the following structure:

{
    "hasHttpSuccessStatusCode": false,
    "httpStatusCode": "451",
    "body": "OK",
    "header": {
        "Accept-Ranges": ["bytes"],
        "Server": ["Restlet-Framework/2.3.5"],
        "Content-Length": ["2"],
        "DemoHeader": ["Demovalue1", "Demovalue2"],
        "Content-Type": ["text/plain;charset=utf-8"]
    }
}
  • hasHttpSuccessStatusCode: Boolean indicating if the HTTP status code represents success.
  • httpStatusCode: The HTTP status code returned by the server.
  • body: The response body as a string.
  • header: An object containing response headers as arrays of string values.