Looking for 

REST API References or REST API Models?

Many users experienced with APIs jump straight to our Object Models and start looking at the potential properties to look-up, change, delete, or populate.

Please allow us to explain how Project Insight's models are organized and how to get their properties. The following article explains HOW Project Insight's Model Properties are designed. If you want to see sample REST calls using JSON or querystring, check out the Request & Response Format article coming up next.

Models and Parameters

I just love these phrases because they make me sound really technical. However, it also sounds intimidating, so let's break these concepts down:

When we say models we mean an object you requested. For example: You can tell Project Insight to get you a specific project based on the project's unique identifying number:

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

But that's just one project in particular. What if I want to "get me all the projects" in Project Insight?

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

Sure, we'll get you a long list of projects - various states, various project managers, various end dates - we'll get you every project in the whole system.

But wait!! I only wanted Active projects!

Ah, you'd like to set some parameters, eh?

curl -X GET --header 'Accept: application/json' 
'https://yourdomain.projectinsight.net/api/project/search?isActive=true

By adding the "isActive=True" we are limiting the number of projects PI returns based on the parameters we set.

Model Properties

Default Model Properties

When you write a REST call for all active projects, what do you think Project Insight is going to return?

A big long list of projects that meet search criteria?

Sure! But are we going to give you the name of the project? The unique identifying guid? A bunch of code that end users can't decipher??

Project Insight is going to return Default Model Properties of that request.

Woah! What are those?!?

For example, if you searched for the most recent code snippit above (all active projects), PI would return the following default properties:

• CompanyDefault_Id
• CustomFieldValue_Id
• Department_Id
• DurationSeconds
• EndDateTimeUserLocal
• EndDateTimeUTC
• Name
• ProjectState
• ProjectStatus_Id
• ProjectType_Id
• ScheduleStartDate
• StartDateTimeUTC
• UrlFull
• WorkPercentComplete
• WorkSeconds

These are the default property values we return for each project when you do not specify which properties you want.

Psssssst! If you're wondering where I got that list from, it's here: Project Model Properties

Selecting Model Properties

You can specify which model properties you want to know ABOUT the Active Projects you've selected:

curl -X GET --header 'Accept: application/json' 
'https://yourdomain.projectinsight.net/api/project/search?isActive=true&modelProperties=Name,ProjectType,ProjectStatus,WorkpercentComplete,PrimaryProjectManager;

I only want to know the Project Type, Project Status, Work Percent Complete, and Primary Project Manager. So I looked up what those properties are called in the Project Model Properties and added that info to my REST call.

Correlated Models

Some model properties are simple. Others are not. Duh.

Some properties you may select are, what we-in-the-software-biz call, a "primitive data type". That means that their values are a straight forward string, date, guid, or integer value. For example, if you ask for the Description of a project, that value has only one answer = the string of text written in the Description text area.

Many of the values you request will have properties of their own.

Let's take Primary Project Manager, for an example. The Primary Project Manager is a User, so this model has default values of its own. You can look up these model properties in the User Model Properties. However, you build your call of those properties the same way you called the Project properties in the first part of the querystring:

curl -X GET --header 'Accept: application/json' 
'https://yourdomain.projectinsight.net/api/project/search?isActive=true&modelProperties=Name,ProjectType,ProjectStatus,WorkpercentComplete,PrimaryProjectManager;User:FirstName,LastName

In this case, I want the PrimaryProjectManager's, First Name and Last Name.    The modelProperties parameter illustrated above will send the properties specified (Name, ProjectType, ProjectStatus, WorkPercentComplete, and PrimaryProjectManager).  The PrimaryProjectManager is a User model, and if there are no properties specified for the User, the default will be sent.  In the example above, we used a semi colon to end the specified properties for the Project model, the default model returned, and we specify the "User" model and then place a colon ":" after that model to specify the properties to include for any User model that is correlated and returned with the Project model.  So in the example above by adding ";User:FirstName,LastName" at the end of the properties specified for the Project model, only the two properties "FirstName" and "LastName" will be returned for the project property "PrimaryProjectManager".     Again if no model properties are specified, then the default properties are returned.   

Another example is to return a Project model with the Tasks property and all sub-tasks of Tasks.   

'https://yourdomain.projectinsight.net/api/project/[Guid]?modelProperties=default,Tasks;Task:ItemNumber,Name,Tasks

In the example above, the Project model will be returned with the default columns and also the Tasks property (an array of top level Task models).   The the keyword "default" is used to return all of the "default" columns of the Project model, plus an additional non-default property "Tasks."   A semi-colon is used to separate the properties being requested for the Project model (the default model returned in this example.  Now properties added after the colon ":" are attributed to the Task model specified because of this part of the string ";Tasks:".   In the example above for each of the Task models in the Tasks property of the Project model, the task ItemNumber, Name, and child Tasks will be returned (recursively).  

A Very Good Place to Start

Now that you know how the model properties are organized in Project Insight's API, you can start to customize the parameters and model properties you call via REST. Check out our Request & Response Format article for examples of these REST calls in JSON and querystring.