Skip to main content
Kinetic Community

Web Services (REST)

The Kinetic Task REST API exposes Kinetic Task API calls via a RESTful web service.  REST is an communication style that utilizes simple, lightweight HTTP calls rather than more complex mechanisms associated with technologies such as RPC or SOAP.  Just about every language and environment has the ability to communicate of HTTP, and REST is intended to be simple enough that it can be consumed without the need for complex libraries or code.

Details

Just like the other API options, the SOAP API exposes the createStart and createDeferred methods.  For more information about utilizing the createStart and createDeferred API methods, please see the parent API Reference page.

Additionally, sample REST clients for the Kinetic Task API are available for Java and Ruby.

Request

Request URL

The Kinetic Task REST API is consumed by submitting an HTTP POST request to a specially formatted URL.

URL Format http://SERVER:PORT/kineticTask/rest/v1/Trigger/API_METHOD

Request Body

The request must include a request body (sometimes referred to as a payload) that includes the necessary API method parameters and use the application/x-www-form-urlencoded content type (this is the same request content type that is used the HTML forms configured to use the POST method).  Below is a sample request payload:

action=Complete&token=AG005056960051rJQmUQPmxIWAUXYJ&results=%3Cresults%3E%3Cresult+name%3D%E2%80%9CStatus%E2%80%9D%3EApproved%3C%2Fresult%3E%3C%2Fresults%3E&

which corresponds to the following

action Complete
token AG005056960051rJQmUQPmxIWAUXYJ
results <results><result name=“Status”>Approved</result></results>

Notice that some characters in the results parameter are encoded.  Most languages have features to automate the encoding of HTTP post parameters, but the HTML specification includes details on formatting.

Request Headers

There are a number of headers that can be passed as part of the HTTP POST request for any API method to control behavior.

Behavior Modifying Headers

Accepts By default, the API results are returned in the same format as a application/x-www-form-urlencoded request.  However, setting the Accepts header to application/json or application/xml will cause the API response to be in the requested format.

Behavior Simulation Headers

X-Simulate-Success=ID

When the X-Simulate-Success header is passed, the actual request parameters are ignored, no actual action is taken, and the API returns a mock successful response using the header value as the resulting trigger id.

X-Simulate-Error=API When the X-Simulate-Error header is passed with a value of API, the actual request parameters are ignored, no actual action is taken, and the API returns an error response that mimics the behavior of  API exception (such as invalid parameters).
X-Simulate-Error=AUTHORIZATION When the X-Simulate-Error header is passed with a value of AUTHORIZATION, the actual request parameters are ignored, no actual action is taken, and the API returns a response that mimics the behavior of an unauthorized request (IE the response an API request would get if a KSL Policy Rule denied access).
X-Simulate-Error=SERVER When the X-Simulate-Error header is passed with a value of SERVER, the actual request parameters are ignored, no actual action is taken, and the API returns an error response that mimics the behavior of an unexpected server exception. 

Response

The response for a Kinetic Task REST Web Service API request is comprised of the HTTP response code, HTTP response headers, and the HTTP response body.

The Kinetic Task REST Web Service API responds with standard HTTP response codes.  For example, an HTTP response code of 500 represents an internal server error, 400 represents a bad request, 401 represents an unauthorized request, and 200 represents a successful REST communication.

There are three HTTP headers that may be returned as part of the API response: X-ID, X-Message, and X-Error-Message.  The X-ID, and X-Message headers are used when the API request was successful and the X-Error-Message response header is used when the API request was not successful.

The API response body will vary depending on the value of the Accepts request header.

Success

HTTP Status Code 200
Response Headers X-ID=ID
X-Message=Created trigger 'ID'.
Response Payload (Default)

ID=ID

                              (JSON) {status: 200, message: "Created trigger 'ID'.", result: {id: "ID"}}
                              (XML) <response>
    <status>200</status>
    <message>Created trigger 'ID'.</message>
    <results>
        <id>ID</id>
    </results>
</response>

API Failure

HTTP Status Code 400
Response Headers X-Error-Message=Unable to locate a task instance with the specified deferral token (e67069a7392dc8ca7347f2edd127f779ef440dc1)
Response Payload (Default)

Unable to locate a task instance with the specified deferral token (e67069a7392dc8ca7347f2edd127f779ef440dc1)

                              (JSON) {
  status: 400,
  message: "Unable to locate a task instance with the specified deferral token (e67069a7392dc8ca7347f2edd127f779ef440dc1)"
}
                              (XML) <response>
    <status>400</status>
    <message>Unable to locate a task instance with the specified deferral token (e67069a7392dc8ca7347f2edd127f779ef440dc1)</message>
</response>

Authentication Failure

HTTP Status Code 401
Response Headers X-Error-Message=security token not provided
Response Payload (Default)

security token not provided

                              (JSON) {
  status: 401, 
  message: "security token not provided"
}
                              (XML) <response>
    <status>401</status>
    <message>security token not provided</message>
</response>

API Methods

createStart

The createStart API method can be called by submitting an HTTP POST of the following parameters to a URL similar to http://SERVER:PORT/kineticTask/rest/v1/Trigger/createStart.

source_name The name of the source root that the desired task tree is associated to.
source_group The name of the source group that the desired task tree is associated to.
source_id The Id of the record that the task tree is being executed on behalf of.
tree_name The name of the tree that will be executed.
results An optional XML string of "results" that will be passed to the start node.
message An optional trigger message.

For additional details about the createStart API parameters, such as how they can be used in the Task Builder or what effect they have, please see the generic API Reference page.

Example API Call

Request URL: http://SERVER:PORT/kineticTask/rest/v1/Trigger/createStart
Request Method: POST
Request Headers
  Content-Type: application/x-www-form-urlencoded
Request Form Data
  source_name: Kinetic Request
  source_group: KEG Catalog > Conference Registration
  source_id: e67069a7392dc8ca7347f2edd127f779ef440dc1
  tree_name: Process Registration


Response Status Code: 200
Response Headers
  Content-Type: text/plain;charset=UTF-8
  X-ID: AG005056b50003ralGTwMDGfEgBLzN
  X-Message: Created trigger 'AG005056b50003ralGTwMDGfEgBLzN'.

Response Payload
  Created trigger 'AG005056b50003ralGTwMDGfEgBLzN'.

 

createDeferred

The createDeferred API method can be called by submitting an HTTP POST of the following parameters to a URL similar to http://SERVER:PORT/kineticTask/rest/v1/Trigger/createDeferred.

token The name of the source root that the desired task tree is associated to.
action The name of the source group that the desired task tree is associated to.
results An optional XML string of "results" that will be passed to the start node.
message An optional trigger message.

For additional details about the createDeferred API parameters, such as how they can be used in the Task Builder or what effect they have, please see the generic API Reference page.

Example API Call

Request URL: http://SERVER:PORT/kineticTask/rest/v1/Trigger/createDeferred
Request Method: POST
Request Headers
  Accept: application/json
  Content-Type: application/x-www-form-urlencoded

Request Form Data
  token: AG005056960051rJQmUQPmxIWAUXYJ
  action: Complete
  results: <results><result name=“Status”>Approved</result></results>
  message: 
Request approved by Ben Christenson on March 1st.

Response Status Code: 200
Response Headers
  Content-Type: application/json;charset=UTF-8
  X-ID: AG005056b50003ralGTwMDGfEgBLzN
  X-Message: Created trigger 'AG005056b50003ralGTwMDGfEgBLzN'.

Response Payload
  {status: 200, message: "Created trigger 'AG005056b50003ralGTwMDGfEgBLzN'.", result: {id: "AG005056b50003ralGTwMDGfEgBLzN"}}