Using Clarity REST APIs

ccppmop159
Clarity
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
REST APIs to leverage the power of
Clarity
by integrating it with our products, build your user interface to interact with
Clarity
's functionality, and bring data in and out of
Clarity
.
Disclaimer
:
Clarity
only supports public REST APIs that are listed in the interactive REST API documentation.
2
Discover REST APIs for
Clarity
You can discover the public REST APIs supported by
Clarity
by:
  1. Reviewing the interactive REST API documentation in
    Clarity
  2. Using the "describe" URL to discover APIs in
    Clarity
Review the Interactive REST API Documentation in
Clarity
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
    .
    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
    .
    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
.
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
REST APIs support numerous API operations for various
Clarity
Objects. Check the tables given below to validate if the operation you want to perform is supported.
Please use the
Clarity
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
Classic 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
Classic PPM
account settings.
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
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 inc
  • orrect, the response is an error message.
Using REST APIs for TSV Attributes
A TSV attribute is supported when you use REST APIs in
Clarity
. 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
For Cost Plans
  • Since cost plans are associated with investments in
    Clarity
    , 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
For Budget Plans:
  • Since
    Clarity
    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. In this case, 5011006 is the internal ID of your target cost plan or budget plan: http://<hostname>:<port>/ppm/rest/v1/costPlans/5011006
For Benefit Plans:
  • For benefit plans in
    Clarity
    , you need to pass the mandatory filter parameter "investmentId".
  • Example: You can use the following GET request to get a list of benefit plans associated with an investment whose investment ID is 5001054: http://<hostname>:<port>/ppm/rest/v1/benefitPlans?filter=(investmentId = 5001054)
  • Group By.jpg
API Enable Custom Objects and Custom Investments
You can API-enable custom master objects, custom and stock sub-objects, and custom or stock virtual attributes so that they are available in
Clarity
. You can use
Classic PPM
or XOG to set the API-enabled flag.
You can only use XOG to API enable stock and custom virtual attributes in
  • Custom master object: You can API enable a custom master object from the studio or using XOG. The API alias will be auto-generated for the API enabled custom master object.
  • Custom Subobjects: You can API enable a custom subobject if it belongs to a
    • Project or investment (or supported abstract objects)
    • API enabled custom master object
    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
    .
Third level sub-objects cannot be API enabled.
  • 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
    Clarity
    . Other types of custom master objects cannot be API enabled.
The only significant difference while using REST APIs for custom objects and custom investments is that the extension parameter is "null" for custom objects and "inv" for custom investments.
The request-response format for custom objects and custom investment objects is consistent with out-of-the-box objects. The REST API for a custom object with API Alias "custAccounts" can be used exactly like a project object.
http://<hostname>:<port>/ppm/rest/v1/custAccounts/"id"/"subObject"/"id"
API Enable Custom Attributes
Quando você cria um atributo personalizado, é necessário ativar o atributo para API a fim de disponibilizá-lo no
Clarity
. Essa definição também permitirá que você acesse o atributo por meio de chamadas de API.
Siga estas etapas:
  1. Efetue logon no
    Classic PPM
    .
  2. Vá para
    Administração
    ,
    Studio
    ,
    Objetos
    .
  3. Pesquise o objeto (como Projeto) que tem o atributo personalizado.
  4. Abra o objeto e vá para a guia
    Atributos
    .
  5. Pesquise o atributo personalizado e clique nele para abrir.
  6. Especifique uma ID exclusiva no campo
    ID de atributo da API
    . O valor deve começar com uma letra minúscula e um sublinhado. Por exemplo, p_uploadImage.
    A ID de atributo da API é a chave de referência para um atributo que aparece no conjunto de resultados de uma chamada de API. Para identificar seus atributos personalizados e validar a exclusividade, é recomendável prefixar suas IDs de atributo da API com uma sequência de caracteres curta consistente. Tornar as IDs de atributo da API exclusivas evita conflitos durante uma atualização futura quando novos atributos são introduzidos. Por exemplo, a ACME Corporation pode atribuir a seguinte ID de atributo da API exclusiva ao seu atributo Conformidade: p_acmeCompliance. Também é recomendável usar a notação do camel case para nomear seus atributos personalizados.
  7. Salve as alterações.
O atributo é ativado para acesso à API e também é disponibilizado no
Clarity
. Você pode configurar o atributo para ficar visível no Layout de painel, no Layout de grade e no painel Detalhes. Para ver o atributo na página Propriedades, configure o blueprint do objeto. Para obter mais informações, consulte a seção Editar um blueprint.
The following custom attribute data types are not supported for the REST APIs:
  • 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.
Retrieve User Profile Information using API
You can retrieve the user profile information of the logged-in user using a REST API. You can use the profile information to personalize the experience for the user such as displaying a personalized message on the UI, set the language preference of the user, and so on.
The logged-in user must have the API-Access permission for this API to work.
Use the following API:
GET http://ClarityHostName:Port/ppm/rest/v1/virtual/userProfile
A successful call returns the following response:
{ "_internalId": 1, "firstName": "John", "lastName": "Doe", "language": "en", "_self": "http://ClarityHostName:Port/ppm/rest/v1/virtual/userProfile", "userName": "jdoe02", "locale": "en_US", "email": "[email protected]" }
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": "
Clarity
Alpha",
"scheduleStart": "2015-04-01T08:00:00",
"scheduleFinish": "2015-09-30T17:00:00",
"description": "New enhancements to
Clarity
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": "
Clarity
Alpha",
"description": "New enhancements to
Clarity
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": "
Clarity
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.