OneSpace Project Center API

Introduction ¶

OneSpace Project Center is a platform for managing work with a team of freelancers or private contributors. This tool empowers businesses to leverage an on-demand workforce in a way that seamlessly blends with an existing enterprise data ecosystem.

The Project Center API provides a simple REST interface to integrate data flows between OneSpace and other critical business processes. This API is an asynchronous, event-driven interface for pushing items into the platform and retrieving completed results. This API has been designed to easily integrate with a variety of existing business data flow processes and tools, bridging the gap between existing enterprise tools and the OneSpace platform.

REST API ¶

This API is a RESTful web service that handles asynchronous communication with the OneSpace platform. For additional information on REST fundamentals, please see REpresentational State Transfer

Each action against the OneSpace API is stateless, containing the full information and parameters required to take an action.

Session Management ¶

This API utilizes token based authorization. All requests into this API require a valid session token. Applications using this API must initially make an authentication request to retrieve a session token. This request passes in credential using basic auth and returns a session token that must be included in subsequent requests.

A given session token will be active for a period of time between 12 and 24hrs before needing to be re-requested. When expired, a general API request will return a 401 “Unauthorized” response, and the client application will need to request a new token.

Item Request Tracking ¶

The Project Center API is idempotent, meaning that each item submitted is processed only once, even if it is delivered multiple times. To facilitate this, all requests require a unique input key for every item. A common practice is to use a GUID (Globally unique identifier) for this key.

Each request into this API can be independently tracked using the supplied request key.

Terminology ¶

Projects ¶

In Project Center, projects are the high-level containers that allow users to organize a collection of jobs for freelancers and internal contributors. Although the API does not directly reference projects, all of the workflows and chains that receive items are nested under a Project Center Project.

Workflows ¶

Workflows in Project Center facilitate the completion of work. A workflow contains one or more Assignments that present work to contributors. Workflows that contain multiple assignments are typically used to add edit or review steps to determine whether or not the original submission should be accepted as output. Think of workflows as the “engine” by which items are completed within Project Center.

Chains ¶

Like workflows, Chains are also “engines” that complete units of work in Project Center. Chains, however, send items through multiple workflows based on business logic. This can be thought of like an automated flowchart, automatically routing items to different workflows based on the state of each item. From an API perspective, these operate just like workflows, in that items are individually released and processed through a chain.

Items ¶

An item represents a single unit of work that can be completed by a workflow or a workflow chain. Items contain a set of inputs (provided by the client) and outputs (created within workflows or chains). These are the lowest level unit of work moving into and out of Project Center.

Batches ¶

Batches represent a logical grouping of items moving through a Project Center workflow or chain. When a client submits work through the user interface, each uploaded file creates a single batch. These can then be tracked, monitored, or exported as a unit. API submissions by default will reside in an automatically generated API batch.

API Authentication ¶

Authentication Tokens ¶

This API utilizes token-based authorization, and all requests into this API require a valid session token. Applications using this API must initially make an authentication request to retrieve a session token. This request passes in credential using basic auth and returns a session token that must be included in subsequent requests.

A given session token will be active for 12hrs before needing to be requested again. When expired, a general API request will return a 401 “Unauthorized” response, and the client application will need to request a new token.

Content-Type: application/json
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Content-Type: application/json

{
  "Token": "MjQ1ZTY3Y2UtMDZjMC00NTFlLWEwNTUtMzMwYjgxODhlMGQ5"
}

Item Commands ¶

This section includes commands for interacting with individual items of work on the OneSpace platform. This includes pushing work into the system, canceling items, and retreiving the status and output of finished items.

Content-Type: application/json
Authorization: Bearer {token}

{
  "inputs": {
    "name1": "value1",
    "name2": "value2"
  }
}

{
  "id": "1cbe149a-59f2-425f-ac02-2d0ea3e3a7fe",
  "status": "pending",
  "inputs": {
    "name1": "value1",
    "name2": "value2"
  },
  "batchId": "dfbd78ba-7d80-46a0-b01b-f14261f61b38"
}

{
  "code": 400,
  "message": "The request input fields did not match the chain schema.",
  "data": [
    {
      "ValidationError": "Unknown columns: [api-input]"
    }
  ]
}

{
  "code": 404,
  "message": "Resource not found",
  "data": null
}

{
  "code": 409,
  "message": "The provided item already exists",
  "data": null
}

Content-Type: application/json
Authorization: Bearer {token}

{
  "id": "5a578946-5ea9-4691-be1f-f208d9f8dde1",
  "chainId": "cabd4990-3409-11e7-94a7-27dfad15f1af",
  "status": "completed",
  "addedAt": "2017-06-23T18:36:56.27Z",
  "inputs": {
    "input1": "Input value",
    "myInput": "Input value 2"
  },
  "outputs": {
    "output1": "Completed output value",
    "myOutput": "Another completed output value"
  },
  "completedAt": "2017-06-23T18:43:45.403Z",
  "batchId": "782d9725-03f6-0000-1817-08d4cac09398"
}

{
  "code": 400,
  "message": "Could not find item 71bb3969-19e1-44c8-93e8-541e0e7ca752 for workflow 20a1f60d-1d70-0000-f270-08d45757cd22",
  "data": null
}

Content-Type: application/json
Authorization: Bearer {token}

{
  "id": "5a578946-5ea9-4691-be1f-f208d9f8dde1",
  "chainId": "cabd4990-3409-11e7-94a7-27dfad15f1af",
  "status": "canceled",
  "addedAt": "2017-06-23T18:36:56.27Z",
  "inputs": {
    "input1": "Input value",
    "myInput": "Input value 2"
  },
  "batchId": "782d9725-03f6-0000-1817-08d4cac09398"
}

{
  "code": 400,
  "message": "Could not find item 71bb3969-19e1-44c8-93e8-541e0e7ca752 for chain 20a1f60d-1d70-0000-f270-08d45757cd22",
  "data": null
}

{
  "code": 405,
  "message": "Could not cancel item 71bb3969-19e1-44c8-93e8-541e0e7ca752 for chain 20a1f60d-1d70-0000-f270-08d45757cd22",
  "data": null
}

Content-Type: application/json
Authorization: Bearer {token}

{
  "inputs": {
    "name1": "value1",
    "name2": "value2"
  }
}

{
  "id": "1cbe149a-59f2-425f-ac02-2d0ea3e3a7fe",
  "status": "pending",
  "inputs": {
    "name1": "value1",
    "name2": "value2"
  },
  "batchId": "dfbd78ba-7d80-46a0-b01b-f14261f61b38"
}

{
  "code": 400,
  "message": "The request input fields did not match the workflow schema.",
  "data": [
    {
      "ValidationError": "Unknown columns: [api-input]"
    }
  ]
}

{
  "code": 404,
  "message": "Resource not found",
  "data": null
}

{
  "code": 409,
  "message": "The provided item already exists",
  "data": null
}

Content-Type: application/json
Authorization: Bearer {token}

{
  "id": "5a578946-5ea9-4691-be1f-f208d9f8dde1",
  "workflowId": "cabd4990-3409-11e7-94a7-27dfad15f1af",
  "status": "completed",
  "addedAt": "2017-06-23T18:36:56.27Z",
  "inputs": {
    "input1": "Input value",
    "myInput": "Input value 2"
  },
  "outputs": {
    "output1": "Completed output value",
    "myOutput": "Another completed output value"
  },
  "completedAt": "2017-06-23T18:43:45.403Z",
  "batchId": "782d9725-03f6-0000-1817-08d4cac09398"
}

{
  "code": 400,
  "message": "Could not find item 71bb3969-19e1-44c8-93e8-541e0e7ca752 for workflow 20a1f60d-1d70-0000-f270-08d45757cd22",
  "data": null
}

Content-Type: application/json
Authorization: Bearer {token}

{
  "id": "5a578946-5ea9-4691-be1f-f208d9f8dde1",
  "workflowId": "cabd4990-3409-11e7-94a7-27dfad15f1af",
  "status": "completed",
  "addedAt": "2017-06-23T18:36:56.27Z",
  "inputs": {
    "input1": "Input value",
    "myInput": "Input value 2"
  },
  "batchId": "782d9725-03f6-0000-1817-08d4cac09398"
}

{
  "code": 400,
  "message": "Could not find item 71bb3969-19e1-44c8-93e8-541e0e7ca752 for workflow 20a1f60d-1d70-0000-f270-08d45757cd22",
  "data": null
}

{
  "code": 405,
  "message": "Could not find item 71bb3969-19e1-44c8-93e8-541e0e7ca752 for workflow 20a1f60d-1d70-0000-f270-08d45757cd22",
  "data": null
}

Webhook Callbacks ¶

When items are completed through OneSpace Project Center, our system will deliver those completed items to API clients via webhook callback events. These webhooks are REST POST events that contain JSON data for completed items. API clients will need to run a service listening on a static IP or URL to receive these events.

Webhook Configuration ¶

Webhooks are currently configured by the OneSpace Client Solutions team as part of the API setup process. This can be any IP or URL the client desires. Note that the configuration for webhook settings can be viewed or modified through API commands. See the Admin Commands section below for details.

Webhook Destinations ¶

OneSpace will push webhook responses to a client service at the configured URI. As Project Center items can be completed at any time, the client webhook receiver should be available at all times. If the destination is unavailable, OneSpace will perform several additional attempts over a period of time before giving up. This can tolerate outages of up to several hours but will result in dropped responses if the destination service is down for an extended period of time.

Webhook Security ¶

OneSpace webhook responses offer two alternatives for client-side security, allowing clients to choose their preferred method of verifying these responses come from a trusted source. These options include:

• HMAC Security - Utilizes a shared secret key along with a cryptographic header that ensures messages are only generated from a trusted source

• oAuth Security - OneSpace utilizes a client supplied username and password to log into a client endpoint to activate a session for delivering webhooks.

HMAC ¶

OneSpace webhook responses utilize HMAC Security to support client-side security. By utilizing a shared secret key, these signatures enable clients to verify that webhook responses are coming from a trusted, secure source. The secure signature is included in the headers of every webhook response sent by OneSpace.

HMAC can be configured from the API Administration page on the OneSpace Project Center platform by selecting HMAC on the Company Webhook Settings Section. Upon saving the HMAC setting, the shared secret key will be displayed on the page:

To validate this signature, client applications would:

• Create an input string from the request body (as text) and the UTC timestamp included in the header (X-OneSpace-Timestamp) [body text + timestamp]

• Generate an HMAC-256 hash using the input string and the (base64 decoded) secret key supplied by OneSpace

• Compare the (base64 encoded) hash with the signature supplied in the webhook header (X-OneSpace-Signature)

var inputValue = Encoding.UTF8.GetBytes(string.Concat( body, timeStampUtc ));
var hashEngine = new HMACSHA256( Convert.FromBase64String( secret_key );
var binaryHash = hashEngine.ComputeHash( inputValue );
var signature = Convert.ToBase64String( binaryHash );
if (signature == onespaceSignature)
{
   // Valid Webhook!
}

OAuth ¶

When utilizing oAuth security, OneSpace will utilize a login and password to collect a session token from a client-supplied endpoint. This token will be included in the headers of every webhook response, guaranteeing that those items are being delivered from a trusted source.

oAuth can be configured from the API Administration page on the OneSpace Project Center platform utilizing the following input parameters:

• oAuth URL: The client’s hosted endpoint OneSpace will use to log into to activate a webhook session

• Username: The username OneSpace will use when connecting to the oAuth URL

• Password: The password OneSpace will use when connecting to the oAuth URL

• Access Token Field: When authenticating against the oAuth URL to retrieve an authentication token, this label tells us which field of the response to use as the access token for a given session.

OneSpace will utilize the session token for all webhook callbacks, and will log in as needed to refresh the token any time sessions expire.

Webhook Callback ¶

This callback delivers completed items for both workflows and chains to a client application. Note that although the example listed below includes both a batch and a chain ID an actual response would contain only one of these IDs, depending on the item type.

Responding to the Webhook ¶

OneSpace will accept an HTTP response of 200 as a valid receipt of the message. Anything else will be interpreted as a failure, sending the response into the exponential back-off retry cycle.

Content-Type: application/json
Authorization: Bearer {token}
X-OneSpace-Timestamp: {Timestamp}
X-OneSpace-Signature: {hmac-signature}

{
  "id": "83d3e829-6c90-4af9-9b01-507a56f3eb2a",
  "inputs": {
    "input1": "value1",
    "myInput": "value2"
  },
  "outputs": {
    "output1": "value1",
    "myOutput": "value2"
  },
  "batchId": "106b4833-1d70-46c0-9dc2-75ea469c7044",
  "chainId": "1ca62230-4fb5-11e7-b76a-6d800f150a6c"
}

{}

Content-Type: application/json
Authorization: Bearer {token}
X-OneSpace-Timestamp: {Timestamp}
X-OneSpace-Signature: {hmac-signature}

{
  "id": "83d3e829-6c90-4af9-9b01-507a56f3eb2a",
  "inputs": {
    "input1": "value1",
    "myInput": "value2"
  },
  "outputs": {
    "987b4833-1d70-46c0-9dc2-75ea469c7044/output-name1": "value1",
    "987b4833-1d70-46c0-9dc2-75ea469c7044/output-name2": "value2",
    "123b4833-4fb5-11e7-b76a-6d800f150a6c/output-name1": "value3",
    "123b4833-4fb5-11e7-b76a-6d800f150a6c/output-named": "value4"
  },
  "batchId": "106b4833-1d70-46c0-9dc2-75ea469c7044",
  "chainId": "1ca62230-4fb5-11e7-b76a-6d800f150a6c"
}

{}

Content-Type: application/json
Authorization: Bearer {token}

{
  "defaultUrl": "https://www.yourwebhook.com/webhook/uri",
  "workflows": [
    {
      "workflowId": "cabd4990-3409-11e7-94a7-27dfad15f1af",
      "webhookUrl": "https://www.yourwebhook.com/webhook/uri"
    }
  ],
  "chains": [
    {
      "chainId": "cabd4990-3409-11e7-94a7-27dfad15f1af",
      "webhookUrl": "https://www.yourwebhook.com/webhook/uri"
    }
  ]
}

Content-Type: application/json
Authorization: Bearer {token}

{
    "defaultUrl": "https://www.yourwebhook.com/webhook/uri",
}

Content-Type: application/json
Authorization: Bearer {token}

{
  "defaultUrl": "https://www.yourwebhook.com/webhook/uri"
}

{
  "defaultUrl": "https://www.yourwebhook.com/webhook/uri"
}

{
  "code": 400,
  "message": "The request body was not properly formatted",
  "data": [
    {
      "ValidationError": "Invalid request body"
    }
  ]
}

Content-Type: application/json
Authorization: Bearer {token}

{
  "url": "https://www.yourwebhook.com/webhook/uri"
}

{
  "webhookUrl": "https://www.yourwebhook.com/webhook/uri",
  "chainId": "d77e57f5-8dcd-4afc-b62a-9a2bd5c6315e"
}

{
  "code": 404,
  "message": "Resource not found",
  "data": null
}

Content-Type: application/json
Authorization: Bearer {token}

{
  "webhookUrl": "https://www.yourwebhook.com/webhook/uri",
  "chainId": "d77e57f5-8dcd-4afc-b62a-9a2bd5c6315e"
}

{
  "code": 404,
  "message": "There is no custom webhook for this workflow.  It will use the company default which can be found by performing a GET on /api/webhooks/default",
  "data": null
}

Content-Type: application/json
Authorization: Bearer {token}

Content-Type: application/json
Authorization: Bearer {token}

{
  "url": "https://www.yourwebhook.com/webhook/uri"
}

{
  "webhookUrl": "https://www.yourwebhook.com/webhook/uri",
  "workflowId": "d77e57f5-8dcd-4afc-b62a-9a2bd5c6315e"
}

{
  "code": 404,
  "message": "Resource not found",
  "data": null
}

Content-Type: application/json
Authorization: Bearer {token}

{
  "webhookUrl": "https://www.yourwebhook.com/webhook/uri",
  "workflowId": "d77e57f5-8dcd-4afc-b62a-9a2bd5c6315e"
}

{
  "code": 404,
  "message": "There is no custom webhook for this workflow.  It will use the default, which can be found by performing a GET on /api/webhooks/default",
  "data": null
}

Content-Type: application/json
Authorization: Bearer {token}

Admin Commands ¶

These commands facilitate interacting with settings for your chains or workflows. These operations are helpful in initial application setup, but are not typically used during normal operations.

Content-Type: application/json
Authorization: Bearer {token}

{
    "id": "d77e57f5-8dcd-4afc-b62a-9a2bd5c6315e",
    "name": "OneSpace API Chain",
    "inputs": [
        {
            "name": "Chain_Input_1"
            "required": "true"
        }
    ],
    "outputs": [
        {
            "workflowId": "f8d2aef0-e690-0000-e3a9-08d50c299145",
            "name": "Output_1"
        }
    ],
    "workflows": [
        {
            "id": "f8d2aef0-e690-0000-e3a9-08d50c299145",
            "name": "Workflow_Name"
        }
    ]
}

Content-Type: application/json
Authorization: Bearer {token}

{
  "batches": [
    {
      "batchId": "f77e57f5-8dcd-4afc-b62a-9a2bd5c6315t",
      "chainId": "d77e57f5-8dcd-4afc-b62a-9a2bd5c6315e",
      "fileName": "input_file.csv",
      "state": "open"
    },
    {
      "batchId": "85b734c4-4bb0-4090-9254-a283aad85030",
      "chainId": "d77e57f5-8dcd-4afc-b62a-9a2bd5c6315e",
      "fileName": "another_input_file.csv",
      "state": "open"
    }
  ]
}

Content-Type: application/json
Authorization: Bearer {token}

{
  "batchName": "MyBatchName"
}

{
  "batchId": "f77e57f5-8dcd-4afc-b62a-9a2bd5c6315t",
  "chainId": "d77e57f5-8dcd-4afc-b62a-9a2bd5c6315e",
  "fileName": "MyBatchName",
  "state": "open"
}

Content-Type: application/json
Authorization: Bearer {token}

{
  "batchId": "f77e57f5-8dcd-4afc-b62a-9a2bd5c6315t",
  "chainId": "d77e57f5-8dcd-4afc-b62a-9a2bd5c6315e",
  "fileName": "API_Batch.csv",
  "state": "open"
}

Content-Type: application/json
Authorization: Bearer {token}

{
  "customSchema": [
    "WorkflowId/OutputName",
    "WorkflowId/OutputName2"
  ]
}

{
  "customSchema": [
    "WorkflowId/OutputName",
    "WorkflowId/OutputName2"
  ]
}

{
  "code": 404,
  "message": "Resource not found",
  "data": null
}

Content-Type: application/json
Authorization: Bearer {token}

{
  "customSchema": [
    "WorkflowId/OutputName",
    "WorkflowId/OutputName2"
  ]
}

{
  "code": 404,
  "message": "No custom schema has been set.  Use a POST to specify an output schema.  By default, the API will include all output data.",
  "data": null
}

Content-Type: application/json
Authorization: Bearer {token}

{}

{
  "code": 404,
  "message": "No custom schema set",
  "data": null
}

Content-Type: application/json
Authorization: Bearer {token}

{
    "workflows" : [{

            "id" : "d77e57f5-8dcd-4afc-b62a-9a2bd5c6315e",
            "name" : "OneSpace API Workflow",
            "inputs" : [{
                    "name" : "Worklfow_Input_1"
                    "required" : "true"
                }
            ],
            "outputs" : [{
                    "name" : "Output_1"
                }
            ]
        }, {

            "id" : "43d8c933-a2c5-4fa5-9d8b-9a34127e2b0f",
            "name" : "Another API Workflow",
            "inputs" : [{
                    "name" : "Worklfow_Input_1"
                    "required" : "true"
                }
            ],
            "outputs" : [{
                    "name" : "Output_1"
                }
            ]
        }
    ]
}

Content-Type: application/json
Authorization: Bearer {token}

{

    "id": "d77e57f5-8dcd-4afc-b62a-9a2bd5c6315e",
    "name": "OneSpace API Workflow",
    "inputs": [
        {
            "name": "Worklfow_Input_1"
            "required": "true"
        }
    ],
    "outputs": [
        {
            "name": "Output_1"
        }
    ]
}

Content-Type: application/json
Authorization: Bearer {token}

{
  "batches": [
    {
      "batchId": "f77e57f5-8dcd-4afc-b62a-9a2bd5c6315t",
      "workflowId": "d77e57f5-8dcd-4afc-b62a-9a2bd5c6315e",
      "fileName": "upload_file.csv",
      "state": "complete"
    },
    {
      "batchId": "c476e78d-f8ea-43ee-9000-80bb805a55dd",
      "workflowId": "d77e57f5-8dcd-4afc-b62a-9a2bd5c6315e",
      "fileName": "another_upload_file.csv",
      "state": "open"
    }
  ]
}

Content-Type: application/json
Authorization: Bearer {token}

{
  "batchName": "MyBatchName"
}

{
  "batchId": "f77e57f5-8dcd-4afc-b62a-9a2bd5c6315t",
  "workflowId": "d77e57f5-8dcd-4afc-b62a-9a2bd5c6315e",
  "fileName": "MyBatchName",
  "state": "open"
}

Content-Type: application/json
Authorization: Bearer {token}

{
  "batchId": "f77e57f5-8dcd-4afc-b62a-9a2bd5c6315t",
  "workflowId": "d77e57f5-8dcd-4afc-b62a-9a2bd5c6315e",
  "fileName": "API_Batch.csv",
  "state": "open"
}