REST API: Documentation for Authorized Developers

ccppmop157
 Clarity PPM REST API web services deliver online data and functionality over a system of Uniform Resource Identifiers (URIs), typically through a series of web links. You can use Clarity PPM REST APIs to leverage the power of Clarity PPM by integrating it with our products, build your user interface to interact with Clarity PPM's functionality, and bring data in and out of Clarity PPM.
Disclaimer
: Clarity PPM only supports public REST APIs that are listed in the interactive REST API documentation. 
Clarity PPM REST APIs are not supported in FEDRAMP environments.  
 
2
 
 
Discover REST APIs for Clarity PPM
You can discover the public REST APIs supported by Clarity PPM by:
  1. Reviewing the interactive REST API documentation in Clarity PPM
  2. Using the "describe" URL to discover APIs in Clarity PPM
Review the Interactive REST API Documentation in Clarity PPM
The link to the interactive REST API documentation for your system is specified in the API section of the System Options page.  
 
Group By.jpg
 
You can access the interactive REST API documentation only when you have the 
API - Access
 right.
Follow
 these steps
:
  1. Click 
    Administration
    General Settings
    System Options
    .
  2. In the API section, review the following fields:
    • REST API Status
       Specifies whether the REST API infrastructure is enabled for the system. If the 
      Disable Rest API Access
       option is checked in CSA, the REST API status is disabled. SaaS customers should contact CA Support to enable or disable the REST APIs. By default, the REST API infrastructure is enabled.
    • API URL
        Defines the URL for accessing the REST APIs.
    • API Documentation URL
       Defines the URL for accessing the REST API reference documentation.
     
    Group By.jpg
     
    You can click the highlighted blue icon to learn more about using the interactive REST API documentation available with Clarity PPM.
    Use the “describe” URL to Discover APIs
     
    You can discover supported APIs by appending “/describe” to the API URL specified in the API section to view the list of supported public APIs for Clarity PPM.
    Example
    : If the base URL for a system is http://<hostname>:<port>/ppm/rest/v1, you can use the following request 
    with the GET operation in an API Development tool like Postman to view the list of supported APIs. 
     
    http://<hostname>:<port>/ppm/rest/v1/describe/
     
    Group By.jpg
     
    You can also use /describe/{resourceName} to return a JSON representation of the metadata for a specific resource. The response includes metadata for the resource (such as supported HTTP methods) and metadata for the API enabled attributes of the resource.
    Example: You can use the following GET operation to see the metadata for the API enabled attributes for the Project object.
    http://<hostname>:<port>/ppm/rest/v1/describe/projects
    You can review the details in the response to understand the various HTTP methods supported by the project object. You can also scroll down to review the various attributes associated with the project object. Some of the details you would be able to learn about each attribute are:
    • Data Type
    • Mandatory or optional
    • Attribute Label
    • Read-only or editable
 
Group By.jpg
 
All these details are extremely useful when you want to understand the metadata associated with objects and attributes.
Standard REST API Methods
You can use REST APIs to develop web applications because REST APIs support CRUD (create, retrieve, delete, and update) operations. You can use a set of HTTP methods known as HTTP verbs to perform CRUD operations. Let’s review the different methods supported in Clarity PPM. 
Remember to review the REST API Authentication topic to ensure that you can use the GET, POST, PUT, PATCH, and DELETE methods successfully. 
GET:
 You can use it to retrieve resources and not modify any information. A GET request never changes the state of a resource. 
Example 1: You can use the following GET method to get the list of all the projects on the system.
http://<hostname>:<port>/ppm/rest/v1/projects
 
Group By.jpg
 
Example 2: You can use the following GET method to get detailed information about a project with the internal id 5002013
http://<hostname>:<port>/ppm/rest/v1/projects/5002013
 
Group By.jpg
 
POST:
 You can use a POST request to create new resources in the system. 
Example: You can use the following POST method and enter the project name and project ID in the body to create a new project. This is an example of a single POST. 
http://<hostname>:<port>/ppm/rest/v1/projects/
 
Group By.jpg
 
PUT:
 You can use PUT to update existing resources. Remember that when you use a PUT request, you need to enter details for the complete rest resource that you want to update. 
  • You can use the header “x-api-force-patch=true” to use PUT as PATCH.
  • There is a batch size limit of 50 when using a PUT operation.
PATCH:
 You can use a PATCH request to make a partial update on a resource.  
Example: You can use the following PATCH method and enter the new project name in the body to update the name of the project whose internal ID is 5052000.
http://<hostname>:<port>/ppm/rest/v1/projects/5052000
 
Group By.jpg
 
DELETE:
 You can use the DELETE requests to delete resources. 
Example: You can use the following DELETE method to delete a specific task from a specific project. In this scenario, 5052000 is the internal ID of the project and 5090001 is the internal ID of the task.
http://<hostname>:<port>/ppm/rest/v1/projects/5052000/tasks/5090001
 
Group By.jpg
 
REST API Operations
Clarity PPM REST APIs support numerous API operations for various Clarity PPM Objects. Check the tables given below to validate if the operation you want to perform is supported.
Please use the Clarity PPM Interactive REST API documentation to view the latest supported APIs and associated operations.
General API Calls
Resource
GET
POST
PATCH
PUT
  DELETE
login
Yes
Yes
logout
Yes
attachments
Yes
lookupValues
Yes
timePeriods
Yes
describe
Yes
Integration
Yes
Yes
Yes
Yes
Project API Calls
Resource
GET
POST
PATCH
PUT
  DELETE
project
Yes
Yes
Yes
Yes
 
tasks
 Yes
Yes
Yes
Yes 
Yes
todos
Yes
Yes
 
Yes 
Yes
assignments
Yes
Yes 
 
Yes
Yes
projectStatusReports
Yes
Yes 
 
Yes
 
benefitPlans
Yes
 
costplans
Yes
Yes
Yes
Yes
Yes
costplandetails
Yes
Yes
Yes
Yes
Yes
issues
Yes
Yes
Yes
Yes
Yes
changes
Yes
Yes
Yes
Yes
Yes
risks
Yes
Yes
Yes
Yes
Yes
Resource/Timesheet API Calls
Resource
GET
POST
PATCH
PUT
  DELETE
timesheets
Yes
Yes
Yes
Yes
timeEntries
Yes
Yes
Yes 
Yes
timesheetNotes
Yes
Yes
 
Yes 
Yes
timeEntryNotes
Yes
Yes 
Yes
Yes
teams
Yes
Yes 
Yes
Yes
Yes 
teamdefinitions
Yes
Yes 
Yes
Yes
Yes
teamdefallocations
Yes
Yes
Yes
Yes
Yes 
resources
Yes
Roadmap Custom Investment API Calls
Resource
GET
POST
PATCH
PUT
  DELETE
roadmaps
Yes
Yes
Yes
Yes
roadmapItems
Yes
Yes
Yes
Yes 
roadmapDependencies
Yes
Yes
Yes 
Yes 
Yes
scenarios
Yes
Yes 
Yes
Yes
scenarioTargets
Yes
Yes 
Yes 
Yes
<Custom Investment>
Yes
Yes 
Yes
Yes
 To create, update, or retrieve project status reports, install the PMO Accelerator add-in.
For data lookup values and error messages, the REST APIs support all the languages supported by 
Clarity PPM
. However, for metadata, the label and resource description are available in end-user's localized language. The remaining are supported in English language. The default language for the end-user is the language selected in the 
Clarity PPM
 account settings.
REST API Authentication
To use the REST APIs, verify that you have the 
API - Access
 right. In addition, verify that you have the appropriate application rights to view or update the specific functional areas in the product. For example, if you have the 
API - Access 
right but do not have the 
Projects - Create
 access right, when you make a POST request for project, you will get a 
401 unauthorized
 error message.
The REST APIs support the following methods for authenticating user requests:
  • Token-based authentication using login and logout API endpoints
  • Basic authentication that is based on an encoded username and password
 By default, an authenticated and authorized user can access the REST APIs. On-premise customers can disable the REST API access at the application server level. See 
CSA Server Properties
 to learn how to do this. SaaS customers can contact CA support to enable or disable REST API access for their users.
Token-Based Authentication with Login and Logout API End Points
The Login and Logout API endpoints are used to implement token-based login. You can access the endpoints using 
/auth
 context.
Login API
The Login API endpoint is a 
POST
 HTTP REST call which requires you to pass user name and password in a basic authentication header with Base64 encoding. The response for the Login endpoint contains an authorization token that is passed as a header parameter to identify the user in any subsequent REST calls to 
Clarity PPM
.
 
Example
:
URL: http(s)://<servername>:<port>/ppm/rest/v1/auth/login HTTP TYPE - POST Header : Name = Authorization, value = Basic <Base64 encoding for username/password> return payload { "authToken": "5096019__059A218A-360D-455B-8E6C-7625B7500A4A", "_self": "http://<servername>:8080/ppm/rest/v1/auth/login" }
To learn more about Token-Based authenticaiton, see REST API: Define Clients and Generate Keys for Integrations with Clarity PPM
Logout API
The Logout API endpoint is a DELETE HTTP REST call to invalidate an auth token. The REST call is used to invalidate the user session created as part of the Login endpoint.
 
Example
:
URL: http(s)://<servername>:<port>/ppm/rest/v1/auth/logout HTTP TYPE - DELETE Header : Name = authToken, value = <authToken value from login> no return payload
Basic Authentication
In Basic authentication, you must provide a username and password with Base64 encoding for every REST API request.
Request Headers for REST APIs
Header
Value
Method
Description
Content-Type
application/JSON
Required
Authorization
Basic YWRtaW46YWRtaW4=
Base64 encoded username/password.
x-api-force-patch
true
PUT
In cases where network infrastructure blocks the PATCH request, PUT can be used to update an existing resource without passing all the attributes. In order for PUT to behave as PATCH, include this header in the request.
x-api-full-response
true
POST, PUT, PATCH
For performance reasons we do not return full responses for these requests, passing this header will return the full object in the response. 
Query Parameters for REST APIs
All query parameters listed below are supported for GET requests for a resource list. Remember that 'fields' is the only query parameter supported for a GET request for only a single resource. 
Parameter
Example
Description
offset
projects?offset=100
The record range for results in context to the limit value. The default value is 0 and cannot be larger than the total number of records. 
limit
projects?limit=50
Limits the number of results to be returned. The default value is 25. 
sort
projects?sort=code desc projects?sort=name,code desc
Determines the order of the data returned. The default order is asc.
fields
projects?fields=name,isActive
Determines the attributes that will be part of the response.
filter
projects?filter=(isActive = true)
 Limit the returned resource to those that match the filter expression.  
links
projects?links=true
The links array contains the URLs to access all associated lookups for a single GET resource. 
expand
projects/5000001?expand=(tasks=(fields=(code,startDate,costType)),teams)
The expand query parameter in URL indicates that resources associated with the REST resource must be represented inline within the response. 
tsvParams
projects/5000001/teams/5020501&tsvParams=(periods=(...),(...)),(workEffortUnit=fte)
The general form of the periods parameter is: (alias1, type1, numberOfPeriods1, startDate1, [calendarType1]), where alias is the API alias of the tsv attribute. 
Please review the interactive REST API documentation and click the blue icon to read more about query parameters, query expressions, and query value formats supported for REST APIs.
Using OBS Attribute Filtering in REST APIs
When we associate an OBS to a Clarity PPM object, an attribute gets created in the object. The OBS filter expression has OBS attribute API alias, operator and value. You can use the following syntax:
(obsAttributeAPIAlias in ((unitId1,unitId2,unitId3), 'U'))
Example:
(deptObs in ((5000001,5000002,5000003), 'U'))
Syntax Rules for Using OBS Attribute Filtering
  • We can always filter by OBS attribute with OBS units and mode.
  • OBS filter supports the use of only the 'IN' operator. Any operator other than this will result in 'invalid filter operator' error.
  • OBS filter value should be enclosed in open and closed parenthesis.
  • unitId1,unitId2,and unitId3 are the OBS unit ids. We can give a single unit Id or multiple unit Ids separated by a comma.
  • The mode can be 'U'/'UA'/'UD', which are the short forms of 'UNITS'/'UNITS AND ANCESTORS'/'UNITS AND DESCENDANTS' respectively. They are case sensitive.
OBS filters can be used with other attribute filters.
Example: 
((deptObs in ((5000001,5000002,5000003), 'U')) and (is_active != false))
Staff OBS Filtering
Staff OBS is an attribute of type number and extendedType lookup in Team object, which is different from normal OBS attribute.
Example:
(staffObsUnit in ((5000001,5000002,5000003), 'UA'))
Using Static Dependent Lookups in REST APIs
Static Dependent Lookups are supported with REST APIs. In order to access the values of a static dependent lookup, you must pass two mandatory filter parameters "entryType" and "exitType", and optionally a parentLookup parameter. Let's review a couple of examples.
lookups/INV_TYPE/lookupValues?filter=((entryType = 'INV_PROCESS_TYPE') and (exitType = 'INV_STAGE_TYPE'))
Using Parameterized Dynamic Lookups
You can use the Parameterized Dynamic Lookups feature using an API. You can find the lookup parameter mapping information from the lookupParameters section in the describeAttributes API. It contains parameters name and dependent attribute’s API ID.
 Sample describeAttributes API response for an attribute of parameterized dynamic lookup:
{ “dataType": "string", "isMultiValued": false, "lookupParameters": { "param_department_code_constrain": "departmentCode", "param_proj_id_constrain": "_internalId" }, "lookupType": "dynamic", "lookupCode": "LOOKUP_PARAM_LOC_ID", "extendedType": "lookup", "name": "locationCode", …… }
 
Sample lookup API URLs
lookups/OBJ_IDEA_PROJECT_CATEGORY_PARAM/lookupValues?filter=((searchText startsWith '%') and (param_type_constrain = 'type100')) lookups/LOOKUP_PARAM_LOC_ID/lookupValues?filter=((searchText startsWith '%') and (param_department_code_constrain = 'Development') and (param_proj_id_constrain = 5001125))
You can search for the parameterized dynamic lookups through the searchText filter parameter. It returns the values containing the user entered text in its displayValue.
Example:
lookups/OBJ_IDEA_PROJECT_CATEGORY_PARAM/lookupValues?filter=((searchText startsWith '%hy') and (param_type_constrain = 'type100'))
 
Here’s the list of validations that is applicable for parameters that dynamic lookup expects:
  • To access the values of a parameterized dynamic lookup, it’s important that the API call must pass values for the parameters that the dynamic lookup expects. If not, the parameter is considered as NULL.
  • If a dependent attribute is not API enabled, the describeAttributes API returns a NULL dependent attribute API ID. User can then pass a value for that parameter as NULL with the lookup API call.
  • If the parameter that the dynamic lookup expects is incorrect, the response is an error message. 
Using REST APIs for TSV Attributes
A TSV attribute is supported when you use REST APIs in Clarity PPM. Let's review a couple of examples where you want to see the allocationCurve of a team instance on a project.
http://host/ppm/rest/v1/projects/5000001/teams?fields=allocationCurve,requirementName,bookingStatus
http://host/ppm/rest/v1/projects/5000001/teams/5020501
Both requests will return the allocationCurve TSV value in the response. Since allocationCurve is defined as a TSV, the response will contain the sum of the TSV over the entire span of the TSV.
Optional Formatting Parameters for TSV Output
When you get TSV attributes as an output with REST APIs, it can be formatted in three distinct ways:
  • The total 'sum' of the attribute can be formatted as 'hours' or 'fte'.
  • The attribute's time-varying data can be included and formatted to specific fiscal periods.
  • The attribute's time-varying data can be included in the 'raw' format, matching exactly how it's stored in the curve.
All of these options are activated via the "tsvParams" parameter.
Using REST APIs for Financials Associated with Investments
Since cost plans are associated with investments in Clarity PPM, you need to pass a mandatory filter parameter "investmentId".  Also, to differentiate between cost plans and budget plans, you also need to pass the "planType" mandatory filter parameter in the GET request. The value of the planType filter parameter should be "FORECAST" for cost plans and "BUDGET" for budget plans. 
Example: You can use the following GET request to get a list of all the cost plans associated with an investment whose investment ID is 5002007.
http://<hostname>:<port>/ppm/rest/v1/costPlans?filter=((investmentId = 5002007) and (planType = 'FORECAST'))
 
Group By.jpg
 
Since Clarity PPM does not have a separate Budget Plan object, you can use the following GET request to get a list of all the budget plans associated with an investment whose investment ID is 5002007.
http://<hostname>:<port>/ppm/rest/v1/costPlans?filter=((investmentId = 5002007) and (planType = 'BUDGET’))
 
Group By.jpg
 
In case you want to get all the details associated with a single cost plan or budget plan, you can use the following GET request.  
http://<hostname>:<port>/ppm/rest/v1/costPlans/5011006
In this case, 5011006 is the internal ID of your target cost plan or budget plan.
API Enable Custom Subobjects and Custom Investments
You can enable specific types of objects for the API by setting a unique API alias or ID.
  • Custom Subobjects: You can API enable a custom subobject if it belongs to a project or investment (or supported abstract objects). If you try to API enable custom subobjects under a master object that is not a project/investment, an error message appears: 
    Cannot API enable custom sub-object if the parent object is not Project or an abstract object
    .
  • Custom Investment Objects: You can create a custom master object with an investment extension. Your custom investment objects are API enabled by default as part of the Clarity PPM 
    "Neue Benutzererfahrung"
    . Other types of custom master objects cannot be API enabled.
API Enable Custom Attributes
You can enable custom attributes for all supported objects and only the supported data types. To enable these custom attributes for the APIs, specify their 
API Attribute ID values 
as described in the following procedure.
Remember that the API Attribute ID must begin with a lowercase letter and should have an underscore after the letter.
 
Follow these steps
:
  1. Click 
    Administration
    Studio
    Objects
    .
  2. Select the object (for example, project).
  3. Click 
    Attributes
    .
  4. Select the attribute that you want to enable for the APIs.
  5. Enter a value in the 
    API Attribute ID
     field as shown in the following image. 
    This image illustrates that you enter a value in the API Attribute ID field.
     
  6. Verify that the ID value meets the following requirements:
    • has an alpha character prefix followed by an underscore
  7. Click 
    Save and Return
    .
 The 
API Attribute ID
 is the reference key for an attribute that appears in the result set of an API call. To identify your custom attributes and validate the uniqueness, we recommend that you prefix your API Attribute IDs with a consistent short string. Making your API Attribute IDs unique prevents conflicts during a future upgrade when new attributes are introduced. For example, ACME Corporation can assign the following unique API Attribute ID to its Compliance attribute: 
acmeCompliance
. We also recommend that you use Camel Case notation to name your custom attributes.
The following custom attribute data types are not supported for the REST APIs:
  • Attachment
  • Time-Varying
Also, the following project attributes that are available with the product as a default are not accessible by the REST APIs:
  • Page Layout
The interactive REST API reference documentation allows you to query the attributes that the REST APIs support, You can also query your custom attributes.
Sample API Requests for Multiple Instances
Create Projects
The following sample request and response is applicable for creating multiple projects.
 
Request
 
POST http://samplehost:8080/ppm/rest/v1/projects HTTP/1.1
{
"d": [
{
"code": "Alpha",
"name": "PPM Alpha",
"scheduleStart": "2015-04-01T08:00:00",
"scheduleFinish": "2015-09-30T17:00:00",
"description": "New enhancements to PPM Alpha",
"priority": 10,
"isActive": true,
"manager": "jsmith"
},
{
"code": "Beta",
"scheduleStart": "2015-04-30T08:00:00",
"scheduleFinish": "2015-07-31T17:00:00",
"description": "Feature development",
"priority": 10,
"isActive": false,
"manager": "jdoe"
}
]
}
 
Response
 
The _results array has a separate entry for every successfully processed record. The _links object lists the links to each lookup attribute type of resource. Any failed and skipped records are listed under the _errors and _skipped objects respectively. If there are no failed and skipped records, the _errors and _skipped objects are omitted in the response. If the complete batch fails, for example, due to a parsing error, the response returns the HTTP status code. The response also returns an error JSON, rather than a separate error object for each record.
{
"_self": "http://samplehost:8080/ppm/rest/v1/projects",
"_links": {
"trackMode": "http://samplehost:8080/ppm/rest/v1/lookups/prTrackMode/lookupValues",
"manager": "http://samplehost:8080/ppm/rest/v1/lookups/BROWSE_PROJMGR/lookupValues",
"pageLayout": "http://samplehost:8080/ppm/rest/v1/lookups/LOOKUP_PROJECT_PAGE_LAYOUT/lookupValues",
"costType": "http://samplehost:8080/ppm/rest/v1/lookups/LOOKUP_FIN_COSTTYPECODE/lookupValues",
"financialStatus": "http://samplehost:8080/ppm/rest/v1/lookups/PAC_PROJECT_STATUS/lookupValues",
"progress": "http://samplehost:8080/ppm/rest/v1/lookups/INVESTMENT_OBJ_PROGRESS/lookupValues",
"percentCompleteCalcMethod": "http://samplehost:8080/ppm/rest/v1/lookups/PRJ_PERCENT_CALC_MODE/lookupValues",
"currencyCode": "http://samplehost:8080/ppm/rest/v1/lookups/LOOKUP_ACTIVE_CURRENCIES/lookupValues",
"assignmentPool": "http://samplehost:8080/ppm/rest/v1/lookups/ASSGN_POOL_TYPE/lookupValues",
"status": "http://samplehost:8080/ppm/rest/v1/lookups/INVESTMENT_OBJ_STATUS/lookupValues",
"chargeCode": "http://samplehost:8080/ppm/rest/v1/lookups/LOOKUP_CHARGE_CODES/lookupValues"
},
"_results": [
{
"_self": http: //samplehost: 8080/ppm/rest/v1/projects/5000001,
"_internalId ": "5000001",
"code": "Alpha",
"name": "PPM Alpha",
"description": "New enhancements to PPM Alpha",
"priority": 10,
"isActive": true,
"scheduleStart": "2015-04-01T08:00:00",
"scheduleFinish": "2015-09-30T17:00:00",
"isOpenForTimeEntry": true,
"etc": 0,
"costType": {
"displayValue": "Operating",
"_type": "lookup",
"id": "OPERATING"
},
"isApproved": false,
"tasks": {
"_self": "http://samplehost:8080/ppm/rest/v1/projects/5000001/tasks"
},
"actuals": 0,
"manager": {
"displayValue": "John, Smith",
"_type": "lookup",
"id": "1"
},
"pageLayout": {
"displayValue": "Project Default Layout",
"_type": "lookup",
"id": "50240"
},
"totalLaborEffort": 0,
"percentComplete": 0,
"priority": 10,
"assignmentPool": {
"displayValue": "Team Only",
"_type": "lookup",
"id": "0"
},
"lastUpdatedDate": "2015-04-01T08:38:31",
"createdDate": "2015-04-01T08:38:31",
"trackMode": {
"displayValue": "PPM",
"_type": "lookup",
"id": "2"
},
"name": "CSM",
"financialStatus": {
"displayValue": "Hold",
"_type": "lookup",
"id": "H"
},
"progress": {
"displayValue": "Not Started",
"_type": "lookup",
"id": "0"
},
"risk": null,
"percentCompleteCalcMethod": {
"displayValue": "Manual",
"_type": "lookup",
"id": "0"
},
"currencyCode": {
"displayValue": "USD",
"_type": "lookup",
"id": "USD"
},
"status": {
"displayValue": "Unapproved",
"_type": "lookup",
"id": "0"
},
"chargeCode": null
}
],
"_errors": [
{
"resourceId": " Beta",
"errorMessage": "CMN-0007: Attribute 'name' is required.",
"errorCode": "validation.requiredFieldMissing"
}
]
}
Read Projects
 
Request
 
GET http://samplehost:8080/ppm/rest/v1/projects HTTP/1.1
 
Note
: If the API endpoint that you construct has sensitive characters, encode the URL using UTF-8 character encoding. For example, while filtering resources, the filter criteria can include sensitive characters such as space, greater than symbol (>), plus symbol. By default, links in the response of all endpoints (such as _self, _next, _previous) are URL encoded when they contain sensitive characters. You do not need to encode these links again.
 
Response
 
By default, the response includes _internalId, _self, and specific attributes as specified in the resource metadata. You can retrieve only selective attributes of a resource by providing comma-separated attribute names in the 
fields
 request parameter. By default, the _links and child resource objects such as _tasks are not included in the response. You can retrieve these objects by providing 
links
 request parameter with value as true. Currently, the child resource objects only have a link to retrieve actual child resource instances. The _next and _previous pagination links appear only when records larger than a page size exist.
{
"_self": "http://samplehost:8080/ppm/rest/v1/projects",
"_totalCount": 1,
"_recordsReturned": 1,
"_pageSize": 25,
"_next": <linktofetchnextpage>,
"_previous": <linktofetchpreviouspage>,
"_results": [{
"_self": "http://samplehost:8080/ppm/rest/v1/projects/5000001",
"_internalId ": "5000001",
"code": "Alpha",
"name": "PPM Alpha",
"tasks": {
"_self": "http://samplehost:8080/ppm/rest/v1/projects/5000001/tasks"
}
}]
}
 
Expand Query Parameter
 
The expand query parameter in the API URL indicates that any child resources associated with the parent resource must be represented inline within the response. For example, to retrieve a project and its tasks, you can send one API request for the project and another one for the tasks list associated with the project. Alternatively, you can use an expand syntax to retrieve both the project and its tasks with a single HTTP request as shown in the following sample:
projects/5000001?expand=(tasks=(fields=(code,startDate,costType)),teams)
You can use other query parameters like 
offset
limit
, and 
filter
 in the same way that 
fields
 is used in the preceding example. Each associated child resource that uses an 
expand
 syntax can include its own query parameters. The query parameters that retrieve child resources in an expand syntax do not impact the parent resource response result.