Getting Started with
Clarity
APIs

Clarity
REST APIs expose
Clarity
data to be consumed by third-party client applications. The APIs enable authorized, external systems to perform CRUD operations on
Clarity
through REST methods. The current API version is v1.
Let us get started with some basic information and then move on to making a simple API call to fetch a list of projects.
URI Structure
The URIs for
Clarity
REST API resources have the following format:
http://<ClarityHostName>:<Port>/ppm/rest/version/context/api-name Examples: http://clarity.xyz.com:8080/ppm/rest/v1/projects http://clarity.xyz.com:8080/ppm/rest/v1/auth/login
In the above examples,
project
and
login
are API names and
auth
is an optional resource context.
Authenticate and Authorize
You can use your
Clarity
user account to authenticate. However, you need the
API-Access
right to use the APIs.
Click here to view a short animation that shows how your administrator can assign this access to you:
APIs leverage the same access rights that your user account has on
Clarity
UI. For example, if you are able to view, create, and edit projects in the UI, you will be able to perform these operations using the APIs too.
Use one of the following authentication types to use
Clarity
APIs:
In this section, we will use basic authentication to keep things simple.
Make Your First API Call
Let us try to retrieve the first ten projects in alphabetical order. Ensure that you have permission to read project data.
Click here to view a short animation that shows how to make your first API call:
Follow these steps to access the Project API:
  1. Open a REST Client and call the following Project API:
    GET http://<ClarityHostName>:<Port>/ppm/rest/v1/projects?limit=10&sort=name
  2. In the Authorization tab, select Basic Auth and specify your credentials.
  3. Send the request.
    The response body lists the first ten projects in alphabetical order.
    Click here to view the sample response.
    { "_pageSize": 10, "_self": "http://<ClarityHostName>:<Port>/ppm/rest/v1/projects?sort=name&limit=10", "_totalCount": 50, "_next": "http://<ClarityHostName>:<Port>/ppm/rest/v1/projects?sort=name&limit=10&offset=10", "_results": [ { "_internalId": 5001125, "code": "PR1001", "name": "4G Upgrade Readiness", "_self": "http://<ClarityHostName>:<Port>/ppm/rest/v1/projects/5001125" }, { "_internalId": 5000003, "code": "csk.appChange", "name": "Application Change Template", "_self": "http://<ClarityHostName>:<Port>/ppm/rest/v1/projects/5000003" }, { "_internalId": 5000002, "code": "csk.appCOTS", "name": "Application COTS Template", "_self": "http://<ClarityHostName>:<Port>/ppm/rest/v1/projects/5000002" },
Congratulations! You have completed your first hands-on trial with
Clarity
APIs.
If you do not have the permission to access Projects, use one of the following methods to view the list of all public APIs. You can then perform a basic get operation on the objects to which you have access.
Send the following request URL in the REST client to fetch a list of
Clarity
APIs:
http://<ClarityHostName>:<Port>/ppm/rest/v1/describe
Alternatively, use the Swagger UI in the following URL to view the interactive API documentation:
http://<ClarityHostName>:<Port>/niku/rest/describe/index.html