Request Format

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

Use a 'GET' method to retrieve some data then create a simple 'POST' to create a project with default properties.

Getting Data

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

The preferred way to make a request 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 (see below).

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. Use the modelProperties parameter (see ModelProperties) to return specific properties.

An alternative way to make an HTTP 'GET' looks like this:

Request URL

	https://yourdomain.projectinsight.net/api/project/active?api-token={api-token}&authentication-token={authentication-token}

The above example will return a collection of active projects using the HTTP method.

Saving Data
Curl

     curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{
         "Name":"Hello World!",
          "ItemContainer_Id": "30467aa7-ca01-42fb-afdf-a2c08cc8b5e1"
           }' 'https://yourdomain.projectinsight.net/ProjectInsight.WebApp/api/project'
	
To create a project, we only need to pass the 'Name' and 'ItemContainer_Id' properties and all other fields will be set with default values.

When you make the save method, you will receive a save object back from the request and details will output in the response body (see below for more details).

Response Format

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.

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

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. This will typically 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.

The most unique thing about performing a 'POST' is that if you call the controller name, 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'


Request Body

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

A 'POST' that creates a new Issue.

Online 12/6/2017