External Executors

External executors are small programs that are run within a users own infrastructure to enable connectivity from Xapix to proprietary or other non-HTTP APIs.

One common use-case for External Executors is for connecting to a PostgreSQL Database. See our onboarding guide here for more details.

Adding an External Executor

Steps
Steps
  1. In a project, select Home > Connectors.

  2. Click External Executor.

  3. Provide a Name for the external executor.

  4. Xapix will generate a URL for you to use in your application to connect to Xapix Cloud.

  5. Apply the URL to your program.

  6. Add any required parameters.

  7. Click Preview Connector (you may need to provide values for detected path parameters). You can view the response in the Preview area.

  8. Click Save Connector.

Example
Example
Adding an External Executor

Configuring the External Executor URL

The following shows an example of a simple python script that increments an input value. It has the following features:

  • Request has id (line 25) and callbacks (line 27) fields

  • Response has callback (line 27) and args (line 28) fields

Let's use this example python script to demonstrate how to use an External Executor.

First, create a new external executor as described above and name it something like

my program

Now, copy the generated URL. For example:

wss://executor.xapix.dev/api/v1/register?name=1st-org/my-first-project/my-program-TknzO8

Open a terminal and create an environment variable. For example, on Windows use the command:

export XAPIX="wss://executor.xapix.dev/api/v1/register?name=1st-org/my-first-project/user-database-6yhdm"

Test to make sure it was set properly. On Windows use echo $XAPIX.

Copy the the following script and save it as test.py.

#!/usr/bin/env python
import os
import asyncio
import json
import time
import websockets
endpoint = os.environ.get('XAPIX')
#
#
print("Starting incrementer loop... ")
async def executor():
while True:
try:
async with websockets.connect(endpoint) as websocket:
print(f"Connected to {endpoint}... ")
while True:
req = json.loads(await websocket.recv())
print(f"< {req}")
reply = {
'type': 'reply',
'id': req['id'],
'result': 'success',
'response': [{'callback': req['callbacks']['success'],
'args': [req['payload']['value'] + 1]}]
}
print(f"> {reply}")
await websocket.send(json.dumps(reply))
except websockets.exceptions.ConnectionClosed:
print("Disconnected, reconnecting in 1 second")
time.sleep(1)
except OSError:
print("Connection refused, reconnecting in 1 second")
time.sleep(1)
asyncio.get_event_loop().run_until_complete(executor())

In a terminal run python test.py. The program then connects to the Xapix endpoint 'XAPIX' (line 9). The program waits for requests.

Back in Xapix, go to Home > Connectors, find the External Executor you created. In this case, it is User Database. Click it to open the Edit Connector page.

Expand Parameters, then payload. Add a payload by clicking New property name, providing a name, and click Literal, in this case. Set the data sample as, say 42. Save the payload by clicking Create.

Click Fetch Preview. The response should be { "body": 43 }. If successful, click Save Connector.

This data source is then added to the list of data sources for the project.