How to access public API on internet with Rossum Function

In many use cases, you will need to access a public API on the internet from a Rossum extension. Such use cases might be very simple and there would be no need to implement and maintain an own HTTP server by using a webhook. A simple custom function being called whenever you need to access the API might be enough. Examples of such use cases would be:

  • making a simple transformation on captured data and sending it to an external system
  • notifying external system about a document status change
  • making requests to the Rossum API

The first step towards using a function with access to the internet, would be to contact us at [email protected]. Knowing the exact use case and your future plans, we will enable the access to internet for functions on your account. In future, the serverless functions would be limited according to your purchased subscription and extensions. However, we can enable the access to internet on your functions in your proof of concept experiments or early integration setups.

Once the access to internet is enabled, you can go ahead and implement your custom function with access to the internet in Node JS 12 runtime.

Making HTTP requests in Rossum function

Currently, we allow to use only the default JavaScript libraries. Therefore you will have to use the standard https library. You can import it in the following manner:

const https = require('https');

In the sample code, we will be using JavaScript Promises for making the API requests so you should add the async keyword in front of the whole Rossum function.

exports.rossum_hook_request_handler = async(...)

Once imported, you can issue requests to the internet. Depending on the external API, you might need to specify a header of the request and a payload. Please, adjust the values of the keys according to your needs.

const options = {
        hostname: 'some-public-api.com',
        path: '/endpoint?example-param1=123',
        method: 'POST',
        headers: {
          'Some-auth-key': '... API TOKEN ...',
          'Content-Type': 'application/json; charset=UTF-8',
        },
      };

let payload = {"key1": "value1"};

Afterwards, you can go ahead and issue the HTTP request.

let dataString = '';

// Define how to process response
const response = await new Promise((resolve, reject) => {
   const req = https.request(options, function(res) {
     res.on('data', chunk => {
       dataString += chunk;
     });
     res.on('end', () => {
       resolve({
         statusCode: 200,
         body: dataString
       });
     });
   });

   req.on('error', (e) => {
     reject({
       statusCode: 500,
       body: 'Something went wrong!'
     });
   });

   // Fill request with payload
   req.write(JSON.stringify(payload))
      
   // Execute request
   req.end()
 });

// Parse response
parsedResponse = JSON.parse(dataString);

It is quite simple. The best way how to see the functions with internet access in action is to have a look at one of our example functions.