REST APIs

The  REST APIs support numerous API operations including the following examples:
ccppmop144
The CA PPM REST APIs can only be used by CA PPM engineering. At this time, the REST APIs are not supported for customer or partner use. Our strategy is to focus on developing robust APIs as we design our new user experience. The APIs may change as we make architectural improvements, add capabilities and optimize performance. We will review our strategy every release and make the APIs publicly available as soon as possible. While the APIs are not intended for public use, the associated documentation is available for use by both internal and external stakeholders. This documentation will eventually form the foundation for the public REST API documentation.
The
Clarity Project and Portfolio Management (PPM)
 REST APIs support numerous API operations including the following examples:
  • Create, update, or retrieve projects
  • Create, update, retrieve, or delete tasks
  • Create, update, retrieve, or delete teams
  • Create, update, retrieve, or delete assignments
  • Retrieve resources
  • Create, update, retrieve, or delete timesheets, time entries, timesheet notes, and time entry notes
  • Retrieve time periods
  • Create, update, or retrieve project status reports
  • Create or update integration instances
: To create, update, or retrieve project status reports, install the Add-in: PMO Accelerator add-in. For the complete list of supported resources, refer to the REST API reference documentation. See Access the APIs and Reference Documentation.
Use the following standard HTTP methods to access the REST APIs:
  • GET
  • POST
  • PUT/PATCH
  • DELETE
For data lookup values and error messages, the REST APIs support all the languages supported by 
Clarity Project and Portfolio Management (PPM)
. However, for metadata, only English language is supported. The default language for the end-user is the language selected in the 
Clarity Project and Portfolio Management (PPM)
account settings.
3
 
Authorize and Authenticate for the APIs
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, a specific user has the 
API - Access 
right but does not have the project create access right. When this user makes a POST request for projects, the user gets a "401 unauthorized" error message.
The REST APIs support the following methods for authenticating user requests:
  • Token-based authentication using login and logout API end points
  • Basic authentication that is based on an encoded username and password
  • Session or cookie-based authentication 
 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 Using Login and Logout API End Points
The Login and Logout API end points are used to implement token based login. You can access the end points using /auth context.
Login API
: The Login API end point 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 end point contains an authorization token that is passed as a header parameter to identify the user in any subsequent REST calls to
Clarity Project and Portfolio Management (PPM)
. See the following 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"}
Logout API
: The Logout API end point 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 end point. See the following 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.
 
Session or Cookie Based Authentication
In session-based authentication, if you log on to
Clarity Project and Portfolio Management (PPM)
on a separate browser tab, the REST API uses the browser session cookies to authenticate.
Enable Custom Attributes for the APIs
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.
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:
    • Contains lowercase or uppercase letters or numeric digits only
    • Contains no spaces or special characters 
    • Is unique for an object 
  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 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 their 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
The interactive REST API reference documentation allows you to query the attributes that the REST APIs support, You can also query your custom attributes.
Access the APIs and Reference Documentation
Use the following URL structure to access the REST APIs:
https://<hostname>:<port>/<context>/rest/<api-version>/<resource-name>
Example
: https://samplehost:8080/ppm/rest/v1/projects
Where
  • ppm
    is the default web context for the REST APIs
  • v1
    is the only supported API version for the current release
  • projects
    is the 
    Clarity Project and Portfolio Management (PPM)
     object that the REST API is accessing 
Use the following URL to access the REST API reference documentation and all supported end points:
   https://<hostname>:<port>/niku/rest/describe/index.html
You can also invoke the endpoints from this URL. See for more information. Verify that you are logged in to
Clarity Project and Portfolio Management (PPM)
 to access the REST API documentation URL.
The web context for the REST API URL is configurable only for On-Premise customers. See
CSA Server Properties
to learn how to configure the web context for the REST API URL. In addition, you can learn how to enable or disable the REST API access.
REST API Discovery
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. For example, the following syntax returns the metadata for the API enabled attributes for the Project object.
http://localhost:8080/ppm/rest/v1/describe/projects
Sample API Requests and Responses
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 end points (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.
View REST API Status and URLs 
You can view the API and documentation URLs and your REST API status in read-only mode.
Follows 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.