REST API: Documentation for Authorized Developers

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. Simple, well-defined operations act upon data resources, objects, and functions in Clarity PPM and communicate various representations of the data with one or more external entities.
ccppmop155
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.
Simple, well-defined operations act upon data resources, objects, and functions in Clarity PPM and communicate various representations of the data with one or more external entities.
REST API web services are based on a structure of defined constraints, a uniform interface, and expectations for performance, modifiability, and scalability.
In a client/server architecture, REST uses a stateless communication protocol, typically HTTP, and a standard interface to exchange resource descriptions between clients and servers. Collectively, the entire capability is known as a
Representational State Transfer Application Programming Interface
, or REST API.
Disclaimer
: The Clarity PPM REST APIs can only be used by our internal engineering teams. At this time, the use of Clarity PPM REST APIs by customers or partners is not supported. 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. Although the APIs are not intended for public use, the associated documentation is available for use by both internal and external stakeholders. This page will eventually form the foundation for the public REST API documentation.
: To take advantage of the Clarity PPM 15.6 REST API CORS BETA functionality, you must be an authorized partner or internal developer. BETA functionality requires Clarity PPM 15.6 or higher.
3
: The Clarity PPM REST API is not supported in production environments and cannot be used in any environment with federated SSO.
REST API Operations
The
Clarity 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 PMO Accelerator add-in.
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 PPM
. However, for metadata, only English language is supported. 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, a specific user has the 
API - Access 
right but does not have the
Projects - 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 with 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 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" }
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.
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 PPM
on a separate browser tab, the REST API uses the browser session cookies to authenticate.
API Enable Custom Objects
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 
    New User Experience
    . 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.
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
Also, the following project attributes that are available with the product as a default are not accessible by the REST APIs:
  • Page Layout
  • Progress
  • Project Category
  • Status
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 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 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.