Request & Response Format

The Project Insight API is a JSON API. Supply a Content-Type: application/json header for 'PUT' and 'POST' requests, and PI's API will receive a valid response object. You must set an Accept: application/json header on all requests.

Basic Call and Response

The base URL for the Project Insight API is https://yourdomain.projectinsight.net/api/

A sample querystring will look something like this:

cURL

curl -X GET --header 'Accept: application/json' 
'https://yourdomain.projectinsight.net/api/project/active'

This request will retrieve and return active projects with default properties:

Response Body

[{
"ProjectType_Id": null,
"ProjectStatus_Id": null,
"CompanyDefault_Id": null,
"Department_Id": null,
"ProjectState": 0,
"ScheduleStartDate": "2014-10-28T00:00:00",
"DurationSeconds": 0,
"WorkSeconds": 0,
"StartDateTimeUTC": "2014-10-28T15:00:00Z",
"EndDateTimeUTC": "2014-10-28T15:00:00Z",
"WorkPercentComplete": 0.00,
"CustomFieldValue_Id": null,
"Name": "MS Project Imported Tasks - Conversion Service Test 1",
"Id": "6d02dbe0-6cfe-4dc9-ba31-b6e6a370c740",
"IdExternal": null
}]

A JSON object returns a list of projects.

Sample Patterns

Project Insight uses a unique pattern to make requests. For simple 'GET' calls, the callout is a named object followed by an action name. Sample query patterns look like:

• /project/{id}
• /task/search
• /time-entry/list 

cURL

curl -X GET --header 'Accept: application/json' 'https://yourdomain.projectinsight.net/api/project/list?ids={ids}'

A 'GET' call that accepts a list of string ids and returns a list of projects.

When performing a 'POST', you will need to provide an Id to perform an update, otherwise, an insert action takes place:

cURL

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{
"Name": "Testing New Issue via REST API",
"ItemContainer_Id" : "{GUID}",
}' 'https://yourdomain.projectinsight.net/api/issue'

Response Body

{
"SavedId": "10d381c1-f0f6-4d40-bf0b-4fa7a55df078",
"Success": true,
"Errors": []
}

The response from a successful 'POST' that created a new Issue

Requesting Model Properties

We explained the basic architecture of our Models and their Model Properties in the article: Using our API Calls

Check out the C# API (REST) Client Tester to build these JSON calls for you. Just select the Model (e.g. Project) and Property (e.g. Project's associated Company) to see the JSON generated for you:

Request Body

Request Url: https://yourdomain.projectinsight.net/api/issue
Sample JSON:
{
"ModelPropertyLists": [
{
"ObjectType": "Project",
"Properties": "Companies,Name"
},
{
"ObjectType": "Company",
"Properties": "Name"
}
]
}

Response Body

[
{
"Companies": [],
"Id": "1311b157-972c-43a4-9c8f-2a99737c31b6",
"IdExternal": null
},
{
"Companies": [
{
"IsActive": true,
"CustomFieldValue_Id": "bbb662d5-12d1-493d-9dd0-f15debe5cb0a",
"Name": "Our Company",
"Id": "bdcede2d-0d12-4e60-a13c-a2f4423c1a16",
"IdExternal": null
},
{
"IsActive": true,
"CustomFieldValue_Id": "fefd0592-9c3d-44b5-9d4f-d1eae0158f6e",
"Name": "Client A",
"Id": "1e66c298-d5d0-4e85-9a88-f07605b7f40f",
"IdExternal": null
}
]

This request gets the projects, their companies, and the company name associated with the projects returned.

Potential Responses

Project Insight responds to successful requests with an HTTP status code of 200. Even if an authentication fails, you will receive a status 200 code with a response object that contains a body message specifying the error.

200 Code

Requests for a 'GET', POST', 'PUT' and 'DELETE' will return successful and the response body may contain a JSON object or another data type value. The example below shows a successfully requested 'POST' method, but failed to perform an insert because a required field parameter was not set.

Request Body

Request Url: https://yourdomain.projectinsight.net/api/issue
Request Method: POST
Status Code: 200
Params: {}

A successful POST.

Response Body

{
"SavedId": "00000000-0000-0000-0000-000000000000",
"Success": false,
"Errors": [{
"Model": null,
"SDK": null,
"Property": "ItemContainer_Id",
"AdditionalInfo": null,
"ErrorMessage": "Parent Item is required.",
"ApiErrorType": 100
}]
}

The request was successful (200 status), but the business logic returns a JSON object populated with error details.

401, 404 & 500 codes

• 401 is the standard for an Unauthorized request
  • A user's credentials (username or password) may be invalid
  • Restricted access may prevent the request from successful authenticating the request
• 404 will return if the requested resource is not found or has been moved
• Lastly, Project Insight returns a 500 status code if there is an Internal Server Error

Although the REST API can handle building a model with complex objects/collections, please note that it may be more efficient to retrieve a set of objects and then perform routines on specific properties. Example, if you choose to return these properties on a project:

props.AddModelPropertyList("default,projectresources,projectstatus,projecttype,tasks,clientjobnumber;task:default,tasks,taskresources");

An exception error (normally "A task was canceled" response error message) may occur due to the request timeout length from processing such a complex object model. A better practice would be to limit which types of properties are returned to avoid unresponsive processing and error results.