1. Get StartedPrime Projects Open Integration API
  2. Ordering, Limit Parameters, and Pagination

Ordering, Limit Parameters, and Pagination

Ordering

By default, Oracle Prime Projects arranges API response objects in ascending order based on their ID values. Additionally, the Oracle Prime Projects API supports response object ordering based on the values of other object properties. Sort endpoint response objects by using the following query parameter pattern:

/primeapi/restapi/<service>/<endpoint>?sort=<propertyName>:<orderingMethod>

Note: Some API services do not support this functionality. See Service Feature Support for more information on the functionality supported by each API service.

Use the sort query parameter to order response objects based on a specified property. For example, the /primeapi/restapi/activity/project/1?sort=finishDate endpoint arranges the contents of the returned response in ascending order based on the value of the finishDate property.

Separate sort query parameter values with a comma to sort by additional properties. If two objects in a response have equal property values for the first sort query parameter value, the second property specified as a sort query parameter is used to order the response data. For example, the primeapi/restapi/activity/project/1?sort=owner,finishDate endpoint orders response objects in ascending order based on the value of the owner property. If two objects have equivalent owner property values, they are instead sorted in ascending order based on the value of the finishDate property.

You can include an optional order query parameter after each sort query parameter value to arrange response objects in ascending or descending order. If no order value is specified, sorted response objects are returned in ascending order. For example, the /primeapi/restapi/activity/project/1?sort=finishDate:DESC sorts response objects in descending order based on the value of the finishDate property. You can also specify a sort order for each sort query parameter value, for example the /primeapi/restapi/activity/project/1?sort=owner:ASC,finishDate:DESC endpoint will arrange objects in ascending order based on the owner property. If any response objects have equal owner property values, they will be sorted in descending order based on the value of the finishDate property.

Notes:

You cannot order response objects based on properties that may contain more than one value.

You cannot order response objects based on the properties of nested objects.

Limits

Some Oracle Prime Projects API endpoints provide a limited number of objects in their response. Limited endpoints return responses containing a fixed number of objects, even if a greater number of those objects exist in your Prime Projects instance. Responses to GET request for the following services contain a maximum of 5,000 objects:

  • Activity
  • Assignment
  • Relationship
  • Scope Item
  • Scope Assignment Actuals Time Phased Data
  • Scope Assignment Baseline Time Phased Data
  • Scope Assignment Planned Time Phased Data
  • Scope Assignment Installed Time Phased Data

By default, the Prime Projects API returns a response containing the first 5,000 requested objects. For example, a GET request to the /activity/{id}/childrenHierarchy endpoint will return a response containing the first 5,000 activities that are children to the specified activity matching the {id} parameter, even if the specified activity has 10,000 child activities.

Limit and Start Parameters

Limit and start parameters specify the range and number of objects limited responses contain. Use these parameters to request objects outside the default range of limited endpoint responses.

The start parameter specifies an initial index value for the range of objects returned in the endpoint response. For example, a GET request to the /activity/1/childrenHierarchy?start=5000 endpoint returns a response containing a maximum of 5,000 activity objects starting from the 5,000 th activity; the response data contains child activities 5,000 to 9,999.

The limit parameter restricts the number of objects returned in a limited endpoint response. The value of the limit parameter must be equal to or less than the maximum limit of 5000. For example, a GET request to the /activity/1/childrenHierarchy?start=5000&limit=20 returns a response containing the first 20 activity objects starting from the 5,000 th activity; the response data contains child activities 5,000 to 5,019.

Note: If a limit parameter value exceeds the maximum limit of 5000, only 5000 objects will be returned in the endpoint response.

Pagination

Endpoints that support the limit parameter also support pagination. Pagination organizes the contents of large responses into smaller, manageable chunks. Paginated endpoints return an object that contains the endpoint response contents and provides additional properties for working with paginated responses, such as next, previous, and count.

Note: Some API services do not support this functionality. See Service Feature Support for more information on the functionality supported by each API service.

Use the limit query parameter to specify the number of objects contained in each page of a paginated response. For example, the /activity/project/1?limit=4 endpoint returns a paginated response containing a maximum of 4 activity objects per response page. You can access the next set of objects in a paginated response by modifying the start and limit query parameters. For example, the /activity/project/1?limit=2&start=1 returns a paginated response containing the fourth and fifth activities associated with the endpoint.

Paginated responses contain a next and previous property. The next property contains a URL you can access to view the next page, or next set of objects, returned by the endpoint. The previous property contains a URL you can access to view the previous page, or previous set of objects, returned by the endpoint. If a paginated response contains the first set of objects returned by an endpoint, the previous property is omitted in the response. If a paginated response contains the last set of objects returned by an endpoint, the next property is omitted.

Paginated responses also include a count property. The count property indicates the total number of objects returned by the given endpoint.

Note: The Prime Projects API supports a maximum limit value of 5000. If you specify an invalid limit query parameter value, such as a number greater than 5000, or a negative number, the API will use the maximum limit and return a paginated response containing 5000 objects.

The following is an example of a paginated response returned by the /activity/project/1?limit=2 endpoint: 

	{ 
      	  "result": [ 
      		  { 
      			 "owner":"jsmith", 
      			 "startDate":"2018-10-14T08:00:00.+0530", 
      			 "recordCount": 1, 
      			 "sequenceNumber": 300, 
      			 "actualDuration": 0, 
      			 "finishDate":"2018-12-11T08:00:00.+0530", 
      			 "activityName":"Structure C1 Assessment", 
      		  }, 
      		  { 
      			 "owner":"mabraham", 
      			 "startDate":"2018-10-27T08:00:00.+0530", 
      			 "recordCount": 1, 
      			 "sequenceNumber": 400, 
      			 "actualDuration": 30, 
      			 "finishDate":"2018-11-10T08:00:00.+0530", 
      			 "activityName":"Pour Concrete", 
      		  }, 
      	], 
      	  "count": 56, 
      	  "next": http://localhost:4000/primeapi/restapi/activity/project/1?limit=2&start=2", 
      	}

Counting

The Prime Projects API provides a REC_COUNT_ONLY query parameter you can use to view the number of objects returned by an endpoint. When the REC_COUNT_ONLY parameter is included in an endpoint request, the API only returns the number of objects associated with the given endpoint.

Note: Some API services do not support this functionality. See Service Feature Support for more information on the functionality supported by each API service.

For example, the /activity/project/1?REC_COUNT_ONLY endpoint may return a response similar to the following:

135

If you include the REC_COUNT_ONLY parameter in a paginated endpoint request, the pagination is ignored and only the number of objects is returned.

For example, the /activity/project/2003?REC_COUNT_ONLY&start=0&limit=10 endpoint may return a response similar to the following:

56

You can also include a REC_COUNT_ONLY parameter in a request that contains filters. Upon receiving the request, the API returns a response containing the number of objects that match the specified filter criteria. For more information on filters, see Entity Filtering.

For example, the /activity/project/2003?filters=activityCode=piping&?REC_COUNT_ONLY endpoint may return a response similar to the following:

3