WebAPIs

Overview

WebAPIs enable systems to call workflows in the Kinetic Platform.

Why Use WebAPIs?

Some scenarios where you might want to use a WebAPI include:

• An external system notifies Kinetic Data that a ticket is closed, triggering a workflow to send the ticket creator a notification email.
• You want to return only a subset of the information normally sent with a Kinetic API call.

Working with WebAPIs

You can view, edit, and create new WebAPIs from the WebAPIs menu from the Space console or at the Space or the Kapp level.

Creating New WebAPIs

Follow these steps to create a new WebAPI:

1. From the Space console, click WebAPIs.
2. Click New WebAPI.
3. Enter a slug that identifies the WebAPI.
4. Choose a request type from the Method list.
5. Select a security policy for the WebAPI from the Security Policy list. The WebAPI will be given Space Admin permissions if no Security Policy is selected.
6. Click Create WebAPI. This opens the Workflow Builder.
7. Create a workflow for the WebAPI using the Workflow Builder.
   1. Use Return nodes to return data to the activity that made the WebAPI call. Return nodes for WebAPIs include an HTML response code and response body. A common practice is to use HTTP response code 200 for successful actions, response code 400 or 500 for unsuccessful actions, and a JSON structure for all response body output.

Calling a WebAPI

WebAPIs are triggered by specially generated URLs. The URL pattern differs slightly between Space-scoped WebAPIs and Kapp-scoped WebAPIs.

You can view and copy example WebAPI snippets from the New WebAPI Run window in the Workflow Builder. Click Run, then click Show Example Snippets.

Working with Inputs

Here are some things to consider when working with WebAPIs:

• If incoming data is www-url-formencoded, use the Request Body Params binding to extract individual parameters using the following structure: <%= @request_body_params['Parameter Name'] %>
• If incoming data is JSON, parse the request body and extract the property manually using the following structure: <%= JSON.parse(@request['Body'])['Property Name'] %>
• If you expect output to be returned from the WebAPI, include a timeout query parameter in your WebAPI calls.

Working with Responses and Outputs

• Do not use HTTP response code 401 (unauthorized) in workflow Return nodes. A 401 response code will be generated automatically by the Platform if the user account attempting to make the WebAPI call does not pass the WebAPI's security policy.
• Workflows without a return node will not generate any custom output to the calling process. If the calling process includes a timeout parameter when making the WebAPI call and there is no return node, a run_results_error response will be returned.
• WebAPI responses will look like this if the WebAPI call does not include the timeout parameter:

   {
       "messageType": "success",
       "message": "Initiated run #1021.",
       "runId": "1021"
   }

• Successful response output completely depends on the WebAPI's return node(s).
• There should be at most one return node triggered for each WebAPI execution.

Follow-up API Calls

If a WebAPI call times out or a process wants to retrieve the output from a previous WebAPI call, you can execute one of the following API calls:

• Space-level WebAPIs: https://SPACE/app/webApiCallbacks/<run id>
• Kapp-level WebAPIs: https://SPACE/app/kapps/<kapp slug>/webApiCallbacks/<run id>

If the WebAPI is complete, the results will be returned. If the WebAPI call is still not complete or does not contain a return node, the response will look like this:

{  
    "errorKey": "run_results_unavailable",  
    "messageType": "error",  
    "message": "The results for run #839268 are unavailable.",  
    "runId": "839268"  
}

Troubleshooting

Timeout Errors

WebAPIs have a maximum timeout length of 30 seconds. Any requests with a longer timeout will execute in the Task engine but will also generate an error with an errorKey of "run_results_error".

{  
    "errorKey": "run_results_error",  
    "messageType": "error",  
    "message": "There was a problem executing run #93130.",  
    "runId": "93130"  
}

Method Errors

If the WebAPI call being made does not match the method defined for the WebAPI, a 404 Not Found error will be returned.

{
    "error": "Unable to locate the <name> WebApi",
    "correlationId": "xxxx",
    "statusCode": 404
}