Call a River to Run Externally using the Rivery API

Knowledge Tutorial
1

Now there is the ability to call rivers to run externally using the Rivery API. In this post we’ll walk through an example use case, where we trigger a river to run and then check its status.

First, we need to create a token to authenticate to the Rivery API. This can be done by admin users in the Rivery console. Navigate to the ‘API Tokens’ page and click ‘Add Token.’

image
image850×541 44.9 KB

Name the token and apply the appropriate scopes. For this example, the token will at minimum need the ‘river:execute’ scope.

image

Once you click ‘Create’, the token value will be available for you to copy. Note - once you close this window the token value will not be visible again.

image

Now that we have a token to authenticate, we can set up our first call to trigger a river. The token we just created will be used in the header of this call.

In addition to our token, we will also need the river_id of the river we wish to run.
We can get this identifier by opening the Rivery console and checking the URL. The river ID is the identifier directly after “/river/” in the URL.

image
image692×512 29.2 KB

Once we have this identifier for the river we would like to run, we can make our first call. An example curl for this run would be (lets assume our token value is “XYZ”):

curl -X POST "https://console.rivery.io/api/run" 
-H "accept: application/json" 
-H "Authorization: Bearer XYZ" 
-H "Content-Type: application/json" 
-d "{ \"river_id\": \"5e8e1eb46b028e37b73f44f0\"}"

The RUN endpoint will return a run_id value in its response.

Next, to check the status of the river we just started running in the previous call, we need to use the check_run endpoint and pass in our run_id value.

curl -X GET "https://console.rivery.io/api/check_run?run_id=3e8a3f767ae549dca79de534139adb00" 
-H "accept: application/json" 
-H "Authorization: Bearer XYZ"

The response returned will look something like this:

{
"tasks_status": 
	[{"task_status": "D", 
	"task_status_message": "MongoDB to File Zone Done Successfully"}, 
	{"task_status": "D", 
	"task_status_message": "load to bq batches Done Successfully"}], 
"run_insert_date": 1586622247382, 
"run_end_date": 1586622275582, 
"river_run_status": "D", 
"river_run_message": "River ods_mogodb_leads Done Successfully"
}

The “river_run_status” will indicate the current status of the run.

D = Done
E = Error
R = Running
W = Waiting

Thus, the workflow can be as follows:

  1. Run a river using RUN endpoint
  2. Check the status of the run using CHECK_RUN endpoint
  3. Based on the status returned, handle the next step in the workflow (i.e. run another river, retry the river, trigger an alert, end the workflow, etc.)

For more information on the Rivery API, see the documentation here and interactive technical documentation here.

2 Likes