Oracle Primavera Cloud REST API

Ordering

By default, the Oracle Primavera Cloud API arranges GET API response objects in ascending order based on their ID values. Additionally, the GET API supports ordering response objects based on other field values. You can sort endpoint response objects using the following query parameter pattern:

/api/restapi/<service>/<endpoint>?sort=<fieldName>:<orderingMethod>

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

To sort by additional fields, separate them with a comma. If two objects have equal values for the first sort field, the second specified field is used to order the response. For example, the endpoint /api/restapi/activity/project/1?sort=owner,finishDate sorts objects in ascending order based on the owner field. If two objects have the same owner value, they are sorted in ascending order by the finishDate field.

You can include an optional order parameter (ASC for ascending, DESC for descending) after each sort field. If no order is specified, the default is ascending. For example, /api/restapi/activity/project/1?sort=finishDate:DESC sorts objects in descending order based on the finishDate field. You can specify a sort order for each field, such as /api/restapi/activity/project/1?sort=owner:ASC,finishDate:DESC, which sorts objects in ascending order by owner and, for objects with the same owner value, in descending order by finishDate.

Notes:

You cannot order response objects based on fields that may contain more than one value.
You cannot order response objects based on the fields of nested objects.
The API supports OrderBy, but Jersey framework may give unexpected results. Use client-side sorting to make sure your results are sorted as expected.
OrderBy is not guaranteed on deprecated fields.

Limits

GET

Primavera Cloud API endpoints limit the number of objects in their responses. All bulk GET endpoints return a maximum of 5,000 objects, even if more objects exist in your Primavera Cloud instance.

By default, the Primavera Cloud API returns the first 5,000 requested objects. For example, a GET request to the /activity/project/{projectId} endpoint will return a paginated response with the first 5,000 activities for the specified project, even if the project has 10,000 activities. A paginated response differs from a normal response. For more information, refer to the Pagination section in this topic.

If your Primavera Cloud instance contains more than 5,000 objects for any bulk GET endpoint, you can retrieve all the objects. For details, see the sections on Limit and Start Parameters and Pagination in this topic.

POST and PUT

The API can only accept a maximum of 5,000 objects in POST or PUT requests. If you need to create or update more than 5,000 objects using the API, you must do so in separate requests. If your request contains more than 5,000 objects, the API will return a response of 400 (Bad Request).

Limit and Start Parameters

limit and start parameters specify the range and number of objects in limited GET API responses. Use these parameters to request objects outside the default range.

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

The limit parameter restricts the number of objects returned. 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 endpoint /activity/1/childrenHierarchy?start=5000&limit=20 returns the first 20 activity objects starting from the 5,000th activity. The response data includes 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 large responses into smaller, manageable chunks. Paginated endpoints return an object that includes the response contents and additional fields for working with paginated responses, such as next, previous, and count.

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

Paginated responses contain next and previous fields. The next field provides a URL to view the next page or set of objects. The previous field provides a URL to view the previous page or set of objects. If the response contains the first set of objects, the previous field is omitted. If the response contains the last set of objects, the next field is omitted.

Paginated responses also include a count field, which indicates the total number of objects returned by the GET endpoint.

Note: The Primavera Cloud API response/request payloads support a maximum limit value of 5000 objects, by default. If you specify an invalid limit query parameter value, such as a number greater than 5000, or a negative number, or a valid query parameter that results in a record count of more than 5000 objects, the API will use the maximum limit and return a paginated response containing 5000 objects.

The following is the format of the paginated response.

"ResultPage": {
    "type": "object",
    "properties": {
        "result": {
            "type": "array",
            "description": "The array of the queried objects.",
            "items": {
                "type ": "ApiEntity"
            }
        },
        "next": {
            "type": "string",
            "format": "url",
            "description": "The link to next set of records of the queried objects, if any."
        },
        "count": {
            "type": "integer",
            "format": "int32",
            "description": "The total record count of the queried objects."
        },
        "previous": {
            "type": "string",
            "format": "url",
            "description": "The link to previous set of records of the queried objects, if any."
        }
    }
}

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://primavera.oraclecloud.com/api/restapi/activity/project/1?limit=2&start=2"
}

Counting

The Primavera Cloud GET API provides a REC_COUNT_ONLY query parameter to view the number of objects returned by an endpoint. When the REC_COUNT_ONLY parameter is included in a request, the API returns only the count of objects associated with the endpoint. For example, a request to /activity/project/1?REC_COUNT_ONLY may return a response like: 135

If you include the REC_COUNT_ONLY parameter in a paginated endpoint request, pagination is ignored and only the number of objects is returned. For example, a request to /activity/project/2003?REC_COUNT_ONLY&start=0&limit=10 may return a response like: 56

You can also use the REC_COUNT_ONLY parameter in a request with filters. The API returns the number of objects that match the specified filter criteria. For more information on filters, see the Entity Filtering section. For example, a request to /activity/project/2003?REC_COUNT_ONLY with header filters and the header value activityCode=piping may return a response like: 3