<h1>Introduction</h1> <p class="lead">Our goal is to provide a simple and easy integration by organizing it around REST. The design is to have predictable, resource-oriented URLs and to use HTTP response codes to indicate API errors. We use built-in HTTP features that can be understood by off-the-shelf HTTP clients. JSON will be returned in all responses from the API.</p> <p>We offer a sandbox environment for setting up and testing the integration.</p> **Sending Tasks through the API is as simple as:** <ol> <li>Sending new Task information to our Task endpoint</li> <li>Using a Webhook to handle the delivery of the Task result</li> </ol> <hr class="os" /> ## Authentication --- > Example Request ```shell curl GET -u {CLIENTHANDLE}:{ACCESSKEY} https:api.onespace.com/workflows/{WORKFLOWHANDLE}/tasks/{ID} ``` > Make sure to replace items wrapped in { } with the appropriate values Each API call is authenticated with [HTTP Basic Authentication](http://en.wikipedia.org/wiki/Basic_access_authentication) by including a OneSpace provided Client Handle as the username and an Access Key as the password in the URL. #### HTTP Basic Authentication Example URL ```shell https:{CLIENTHANDLE}:{ACCESSKEY}@api.onespace.com/workflows/{WORKFLOWHANDLE}/tasks/{ID} ``` **Basic OneSpace API Authentication Rules** <ol> <li>All API requests must be made over [HTTPS](http://en.wikipedia.org/wiki/HTTP_Secure).</li> <li>Provide your Client Handle as the basic authentication username and your Access Key as the password.</li> <li>You must authenticate for all requests.</li> </ol> <hr class="os" /> ## Versioning --- > Example Request ```shell curl -X PUT https://api.onespace.com/workflows/{WORKFLOWHANDLE}/tasks/{ID} \ -H "Content-Type: application/json" \ -H "CS-API-Version: 2014-08-28" \ -u {CLIENTHANDLE}:{ACCESSKEY} \ -d '{ "input":{ "name1":"value1", "name2":"value2" } }' ``` When we make backwards-incompatible changes to the API, we release new dated versions. The current version is 2014-08-28. It is recommended to always provide a version on each API request. If a version is not provided, we will assume the request is for the latest API Version. To include the version for a request, insert a custom header with the name "CS-API-Version" that includes a string representing a date value. The date must be in the ISO 8601 format of "YYYY-MM-DD". Be aware that if you don't provide a version, you run the risk of the API becoming incompatible with your integration. In most cases, not providing an API Version would only be recommended during initial API integration testing. <hr class="os" /> ## HTTP Headers --- > Example Request ```shell curl -X PUT https://api.onespace.com/workflows/{WORKFLOWHANDLE}/tasks/{ID} \ -H "Content-Type: application/json" \ -H "CS-API-Version: 2014-08-28" \ -u {CLIENTHANDLE}:{ACCESSKEY} \ -d '{ "input":{ "name1":"value1", "name2":"value2" } }' ``` Each API method uses the combination of standard and custom header information to provide needed API data to process a request. We have listed below the headers used by our API along with a description of each. #### Accept The Accept header field can be used to specify certain content types which are acceptable for the response. This is optional and all responses will be of type "application/json". #### Content-Type The Content-Type header field indicates the content type of the body sent to the API. This is required if a body is needed for an API method and should always be "application/json". #### CS-API-Version The CS-API-Version header is a required field used to provide the version of the API that should be used. See [Versioning](/#versioning) for more details. <hr class="os" /> ## Errors --- > Example Error Body Response Format Example 1 ```shell { "code": "65577" , "message": "Invalid Task input data.", "data": [ "field1": "Required field not found." ] } ``` > Example Error Body Response Format Example 2 ```shell { "code": "66868" , "message": "Invalid Task endpoint.", "data": null } ``` The OneSpace API uses conventional HTTP response codes to indicate success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g. a required parameter was missing, etc.), and codes in the 5xx range indicate an error with OneSpace's servers. To review all standard status code definitions, please review the [W3 HTTP/1.1 document](http://www.w3.org/Protocols/HTTP/1.1/draft-ietf-http-v11-spec-01.html#Status-Codes). Certain errors will have additional information represented in the response body. #### Custom Response Error Body Format Name | Description -------------- | -------------- code | The type of error returned. message | A human-readable message giving more details about the error. data | This field is either null or contains an array of name-value pairs that give more detailed information such as specific validation fields that caused the error. <hr class="os dark" /> # Tasks ## Create a Task **Creates a Task for a specific Workflow.** > Example Request ```shell curl PUT https://api.onespace.com/workflows/{WORKFLOWHANDLE}/tasks/{ID} \ -H 'Content-Type: application/json' \ -H 'CS-API-Version: 2014-08-28' \ -u {CLIENTHANDLE}:{ACCESSKEY} \ -d '{ "input":{ "name1":"value1", "name2":"value2", ... } }' ``` > Example Response ```shell { "id": "1cbe149a-59f2-425f-ac02-2d0ea3e3a7fe", "status": { "code": "open", "cancelable": true, "canceled": false, "completed": false } "input": { "name1": "value1", "name2": "value2", ... } } ``` The ID value in the PUT URL will be the same ID value returned in the response data and the Webhook notification events. This value must be a valid GUID generated by the API consumer. It should be used to recognize and reconcile the Task from creation to Webhook notification events. #### Headers Name | Value | Required -------------- | -------------- | -------------- Method | PUT | required URI | https://api.onespace.com/workflows/{WORKFLOWHANDLE}/tasks/{ID} | required [Accept](/#accept) | application/json | optional [Content-Type](/#content-type) | application/json | required [CS-API-Version](/#cs-api-version) | [ISO 8601](http://en.wikipedia.org/wiki/ISO_8601) Date | optional #### Data Name | Description -------------- | -------------- input | A set of name/value pairs that are used to provide the input data required for a given Workflow. #### Response Data Name | Description -------------- | -------------- id | The ID of the Task. This will be the same ID used in the PUT request URL and the value must be a valid GUID. [status](/#task-status) | The current status of the Task. The status will be returned as an object. [See status object documentation](/#task-status). input | A set of name/value pairs that are used to provide the input data required for a given Workflow. #### Put specific error responses HTTP Code | HTTP Message | Internal Code | Internal Message | Internal Data -------------- | -------------- | -------------- | -------------- | -------------- 400 | Bad Request | 65464 | Unable to parse request body. | null 400 | Bad Request | 54421 | Invalid request information. | Key value pairs of name and message descriptions for each error found 400 | Bad Request | 65577 | Invalid Task input data. | Key value pairs of name and message descriptions for each error found 403 | Forbidden | 61286 | Task is canceled. | null 404 | Not Found | 66868 | Invalid Task endpoint. | null 409 | Conflict | 50688 | A conflicted Task was found. | null A 409 Conflict response indicates that a duplicate Task was found with the same ID, however the inputted data is different. A duplicate Task with the same ID and the same input data will result in a 200 OK response. In both cases, no new Task was created. <hr class="os" /> ## Retrieve a Task **Retrieves a Workflow Task.** > Example Request ```shell curl -X GET https://api.onespace.com/workflows/{WORKFLOWHANDLE}/tasks/{ID} \ -H "CS-API-Version: 2014-08-28" \ -u {CLIENTHANDLE}:{ACCESSKEY} ``` > Example Response ```shell { "id": "1cbe149a-59f2-425f-ac02-2d0ea3e3a7fe", "status": { "code": "open", "cancelable": true, "canceled": false, "completed": false }, "input": { "name1": "value1", "name2": "value2", ... }, "output": { "name1": "value1", "name2": "value2" ... } } ``` #### Headers Name | Value | Required -------------- | -------------- | -------------- Method | GET | required URI | https://api.onespace.com/workflows/{WORKFLOWHANDLE}/tasks/{ID} | required [Accept](/#accept) | application/json | optional [CS-API-Version](/#cs-api-version) | [ISO 8601](http://en.wikipedia.org/wiki/ISO_8601) Date | optional #### Response Data Name | Description -------------- | -------------- id | The ID of the Task. This will be the same ID used in the PUT request URL and the value must be a valid GUID. [status](/#task-status) | The current status of the Task. The status will be returned as an object. [See status object documentation](/#task-status). input | A set of name/value pairs that are used to provide the input data required for a given Workflow. output | A set of name/value pairs that are the results of the completed Task. #### Method specific error responses HTTP Code | HTTP Message | Internal Code | Internal Message | Internal Data -------------- | -------------- | -------------- | -------------- | -------------- 400 | Bad Request | 54421 | Invalid request information. | Key value pairs of name and message descriptions for each error found 403 | Forbidden | 61286 | Task is canceled. | null 404 | Not Found | 66868 | Invalid task endpoint. | null <hr class="os" /> ## Cancel a Task **Cancels a Workflow Task.** > Example Request ```shell curl -X DELETE https://api.onespace.com/workflows/{WORKFLOWHANDLE}/tasks/{ID} \ -H "CS-API-Version: 2014-08-28" \ -u {CLIENTHANDLE}:{ACCESSKEY} ``` #### Headers Name | Value | Required -------------- | -------------- | -------------- Method | DELETE | required URI | https://api.onespace.com/workflows/{WORKFLOWHANDLE}/tasks/{ID} | required [Accept](/#accept) | application/json | optional [CS-API-Version](/#cs-api-version) | [ISO 8601](http://en.wikipedia.org/wiki/ISO_8601) Date | optional #### Method specific error responses HTTP Code | HTTP Message | Internal Code | Internal Message | Internal Data -------------- | -------------- | -------------- | -------------- | -------------- 400 | Bad Request | 54421 | Invalid request information. | Key value pairs of name and message descriptions for each error found 403 | Forbidden | 56947 | Task is not cancelable. | null 404 | Not Found | 66868 | Invalid Task endpoint. | null <hr class="os" /> ## Task Status A Task status is represented as an object. Using this format makes it easier to work with the API by answering some questions that may not be as clear with a simple status code. Property Name | Description -------------- | -------------- code | The current state of a Task represented as a string. <br/>Options are: "open", "canceled", and "completed". cancelable | A boolean value used to determine if the Task is in a cancelable state. canceled | A boolean value indicating if the Task is canceled. completed | A boolean value indicating if the Task has been completed. <hr class="os dark" /> # Webhooks > Example POST request to client endpoint ```shell { "id": "73732127-00a1-d4fe-26ee-08d1b047f0dc", "input": { "List": "This is the list of titles", "Opt1": "Title option 1", "Opt2": "Title option 2", "Opt3": "Title option 3" }, "output": { "RadioList": "Title option 3" } } ``` With OneSpace Webhooks, you can receive Task completed or canceled event notifications as they happen. When the event occurs, OneSpace sends a result object that contains all the relevant information about the processing of a Task. An HTTP POST request with the result information will be sent to a URL on your server. #### Setting up a webhook During the API integration with OneSpace, you can provide a Webhook URL destination that will be used when sending the Task completed or canceled event notifications. #### Receiving a webhook Configuring your server to receive a Webhook is similar to creating any page on your website. With PHP, you might create a new .php file on your server. With some other frameworks, you might add a new route with the desired URL. Remember, with Webhooks, your server is the server receiving the request. Webhook data is sent as JSON in the request's body. An ID value will be included and should be used to reconcile the event with a previously created Task. The event type will be represented in the URL query string with either a "canceled" or "completed" value. The ID value in the PUT URL will be the same ID value sent in the Webhook notification events. This value is a valid GUID and should be used to recognize and reconcile the Task from creation to Webhook notification events. #### Responding to a Webhook To acknowledge that you received the Webhook without problems, your server should return a 200 HTTP status code. Any other information you return in the request headers or request body will be ignored. Any response code other than a 200, will indicate to OneSpace that you did not successfully consume the Webhook notification. When a Webhook is returned without the 200 status code, OneSpace will continue trying to send the Webhook, spacing out repeated calls using [exponential backoff](http://en.wikipedia.org/wiki/Exponential_backoff).