Back to top

OneSpace Project Center API

Note: This documention covers the Project Center Client API released in June of 2017. If you are using our legacy API for managed projects, that documentation can be found here:    OneSpace Legacy API Guide

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.

hierarchy

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.

Get Authentication Token

This function should be used on application startup or after session timeout to retrieve a new authentication token. The returned token must be included in the headers of all general API requests.

Get Authentication Token
GET/api/authenticate

Example URI

GET /api/authenticate
Request
HideShow
Headers
Content-Type: application/json
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Response  200
HideShow

The login request was successful, and a valid session token is returned

Headers
Content-Type: application/json
Body
{
  "token": "MjQ1ZTY3Y2UtMDZjMC00NTFlLWEwNTUtMzMwYjgxODhlMGQ5"
}
Response  401
HideShow

Invalid credentials

Response  500
HideShow

Internal System Error

API Commands

Create a Chain Item

Publishes an item into the supplied Workflow Chain. Note that this request can be tracked via the given item ID, which will also be returned to the user application in the response webhook. The Chain ID is retrieved for a given chain through the Project Center application, and will not change after the chain has been created.

Create Chain Item
PUT/chains/{chainId}/items/{itemId}

Example URI

PUT /chains/d77e57f5-8dcd-4afc-b62a-9a2bd5c6315e/items/1cbe149a-59f2-425f-ac02-2d0ea3e3a7fe
URI Parameters
HideShow
chainId
guid (required) Example: d77e57f5-8dcd-4afc-b62a-9a2bd5c6315e

ID of the Chain

itemId
guid (required) Example: 1cbe149a-59f2-425f-ac02-2d0ea3e3a7fe

ID of the Item

Request
HideShow
  • Note: Request must include a valid authentication token

  • inputs: Includes key value pairs of input values for the workflow chain item

Headers
Content-Type: application/json
Authorization: Bearer {token}
Body
{
  "inputs": {
    "name1": "value1",
    "name2": "value2"
  }
}
Response  202
HideShow

The request has been accepted and has passed initial validation. The final response will be an asynchronous response sent as a OneSpace webhook.

  • id : The ID of the item passed in

  • status : Status of the item (on success, it should be “open”)

  • inputs : The key, value pairs of all of the input values for the item

  • batch : The ID of the batch that contains the item

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

Bad Request: Invalid put request - please see error message for more details

  • code : System error code

  • message : Human-readable error message

  • data : Additional data for the error message (if needed)

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

Resource not found: Improper URI for this operation

  • code : System error code

  • message : Human-readable error message

  • data : Additional data for the error message (if needed)

Body
{
  "code": 404,
  "message": "Resource not found",
  "data": null
}
Response  409
HideShow

The supplied item ID has already been requested

  • code : System error code

  • message : Human-readable error message

  • data : Additional data for the error message (if needed)

Body
{
  "code": 409,
  "message": "The provided item already exists",
  "data": null
}
Response  500
HideShow

Internal System Error

Create a Workflow Item

This action publishes an item into the supplied workflow. Note that this request can be tracked via the given item ID. Note that the itemId value will also be returned to the user application in the response webhook.

Create Workflow Item
PUT/workflows/{workflowId}/items/{itemId}

Example URI

PUT /workflows/d77e57f5-8dcd-4afc-b62a-9a2bd5c6315e/items/1cbe149a-59f2-425f-ac02-2d0ea3e3a7fe
URI Parameters
HideShow
workflowId
guid (required) Example: d77e57f5-8dcd-4afc-b62a-9a2bd5c6315e

Id of the Workflow

itemId
guid (required) Example: 1cbe149a-59f2-425f-ac02-2d0ea3e3a7fe

Id of the Item

Request
HideShow
  • Note: Request must include a valid authentication token

  • inputs: Includes key value pairs of input values for the workflow chain item

Headers
Content-Type: application/json
Authorization: Bearer {token}
Body
{
  "inputs": {
    "name1": "value1",
    "name2": "value2"
  }
}
Response  202
HideShow

The request has been accepted and has passed initial validation. The final response will be an asynchronous response sent as a OneSpace webhook.

  • id : The ID of the item passed in

  • status : Status of the item (on success, it should be “open”)

  • inputs : The key, value pairs of all of the input values for the item

  • batch : The ID of the batch that contains the item

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

Bad Request: Invalid put request - please see error message for more details

  • code : System error code

  • message : Human-readable error message

  • data : Additional data for the error message (if needed)

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

Resource not found: Improper URI for this operation

  • code : System error code

  • message : Human-readable error message

  • data : Additional data for the error message (if needed)

Body
{
  "code": 404,
  "message": "Resource not found",
  "data": null
}
Response  409
HideShow

The supplied item ID has already been requested

  • code : System error code

  • message : Human-readable error message

  • data : Additional data for the error message (if needed)

Body
{
  "code": 409,
  "message": "The provided item already exists",
  "data": null
}
Response  500
HideShow

Internal System Error

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.

Destination Availability

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 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.

Webhook Response

This function delivers a completed item to a client application, delivering all of the inputs and outputs for the given item. Note that this will use the full URI as configured for the client.

Expand the “Request” section below for details on the webhook format

Webhook Response
POST/

Example URI

POST /
Request
HideShow
  • id - Input ID of the item as it was submitted originally

  • inputs - name/value pairs of all of the item inputs as specified by the user

  • outputs - name/value pairs of all of the Project Center generated values on the item

  • batchId - The ID of the batch for the given item

  • chainId - The ID of the chain for the item (if applicable)

  • workflowId - The ID of the chain for the item (if applicable)

Headers
Content-Type: application/json
Authorization: Bearer {token}
Body
{
    "id" : "83d3e829-6c90-4af9-9b01-507a56f3eb2a"
    "inputs" : {
        "input-name1": "value1",
        "input-name2": "value2"
    },
    "outputs" : {
        "output-name1": "value1",
        "output-named": "value2"
    },

    "batchId": "106b4833-1d70-46c0-9dc2-75ea469c7044",
    "chainId" : "1ca62230-4fb5-11e7-b76a-6d800f150a6c"
}
Response  200
HideShow

Successful Response

Note that this is the expected response to a webhook callback. OneSpace will assume any other response code is an error that must be retried.

Body
{}

Generated by aglio on 23 Jun 2017