Web Services (REST)
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"}}