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! It's not as complicated as it sounds - I promise!

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;PrimaryProjectManager:FirstName,LastName

In this case, I want the PrimaryProjectManager's First Name and Last Name. That's it. Don't send me the all the PrimaryProjectManager's Default Model Properties. I don't want all that. I only want what I asked for.

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.