SAP Cloud ALM Extend with APIs (Part 4): Work with SAP Cloud ALM API REST endpoints

Let’s see how to interact with the different APIs of SAP Cloud ALM.

Get the URL Tokens

As already seen in the previous blog, service instances are created in SAP BTP to allow external applications to consume services from SAP Cloud ALM.

The Service keys contains 3 parts:

• clientID: public identifier for the service instances
• clientSecret:  known only to the BTP service broker and the authorisation server.
• tokenURL: give users access permission for SAP Cloud ALM

let tokenUrl = pm.environment.get("TOKEN_URL");
let clientId = pm.environment.get("CLIENT_ID");
let clientSecret = pm.environment.get("CLIENT_SECRET");

Before consumers can access SAP Cloud ALM API, you must obtain an access token that grants access to that API.

let getTokenRequest = {
  method: "POST",
  url: token_URL,
  header: {
    "Content-Type": "application/x-www-form-urlencoded",
  },
  body: {
    mode: "urlencoded",
    urlencoded: [
      { key: "grant_type", value: "client_credentials" },
      { key: "scope", value: "" },
      { key: "client_id", value: clientId },
      { key: "client_secret", value: clientSecret },
    ],
  },
};

The access token responses contain the list of scopes attached to the service instance. An optional scope request parameter can be passed to filter the scopes response.

pm.sendRequest(getTokenRequest, (err, response) => {
     let jsonResponse = response.json(),
     accessToken = jsonResponse.access_token;
     pm.environment.set("TOKEN", accessToken);
     pm.variables.set("TOKEN", accessToken);
});

Understand SAP Cloud ALM endpoints

SAP Cloud ALM APIs endpoints are based on the following pattern:

• https://<region>.alm.cloud.sap/api/<api>/<version>/<resources>

• region: SAP BTP region (ex: eu10, eu20, …)
• api_name: name of the API. (ex: calm-tasks, calm-analytics, …)
• version: version of the API (ex: v1)
• resources: API resources (ex: tasks, providers, …)

Examples

https://eu10.alm.cloud.sap/api/calm-analytics/v1/providers
https://eu10.alm.cloud.sap/api/calm-tasks/v1/tasks
https://eu10.alm.cloud.sap/api/calm-projects/v1/projects

Working with resources

SAP Cloud ALM Projects

GET:  https://eu10.alm.cloud.sap/api/calm-projects/v1/projects

Description:  Get the list of projects.

API HUB: https://api.sap.com/api/CALM_PJM/resource

Headers: authorisation Bearer{{TOKEN}}

Request:

Response:

[
    {
        "id": "35b22fcc-cd63-4d6f-97ba-3a2be95a7367",
        "name": "Demo create with timebox",
        "status": "C"
    },
    {
        "id": "92adaa5a-2c76-48c5-8855-53efe3b8ec0d",
        "name": "demo with ms",
        "status": "O"
    },
]

SAP Cloud ALM Tasks

GET:  https://eu10.alm.cloud.sap/api/calm-tasks/v1/tasks?projectId=35b22fcc-cd63-4d6f-97ba-3a2be95a7367

Description:  Get the list of tasks assigned to a specific project.

API HUB: https://api.sap.com/api/CALM_TKM/resource

Headers: authorisation Bearer{{TOKEN}}

Request:

Response:

[
    {
        "id": "0034f9f2-b187-486b-8b97-92b349b19520",
        "projectId": "35b22fcc-cd63-4d6f-97ba-3a2be95a7367",
        "title": "Setup Project",
        "type": "CALMTMPL",
        "status": "CIPTKOPEN",
        "externalId": null,
        "dueDate": null
    },
    {
        "id": "660a3ad4-5c2d-45ea-97d7-94f016502670",
        "projectId": "35b22fcc-cd63-4d6f-97ba-3a2be95a7367",
        "title": "Setup Central Business Configuration Integration (Optional)",
        "type": "CALMTMPL",
        "status": "CIPTKOPEN",
        "externalId": null,
        "dueDate": null
    }
]

SAP Cloud ALM Analytics

GET: https://eu10.alm.cloud.sap/api/calm-analytics/v1/analytics/providers/data

Description: Get time-series for the last X Days for the Demo Tasks data provider.

API HUB: https://api.sap.com/api/CALM_ANALYTICS/resource

Headers: authorisation Bearer{{TOKEN}}

Request:

{
    "format": "time_series",
    "timeRange": {
        "semantic":"L60D"
    },
    "queries": [
        {
            "name": "legend1",
            "provider": "DEMO_TASKS",
            "version":"V1",
            "columns": {
                "dimensions": [
                    "project"
                ],
                "metrics": [
                    {
                        "measure": "Count"
                    }
                ]
            },
            "filters": [   
                   {
                        "key":"project",
                        "value":["CRM"]
                    },
                    {
                        "key":"AggregatedStatus",
                        "value":["closed"]
                    }
            ]
        }
    ]
}

Response:

[
    [
        {
            "serieName": "legend1",
            "totalCount": 2,
            "group": "legend1",
            "measure": "Count",
            "attributes": [],
            "dataPoints": [
                [
                    0,
                    20210618000000
                ],
                [
                    0,
                    20210617000000
                ]
            ],
            "message": ""
        }
    ]
]

In the next blog, we will discuss how to build a Digital Boardroom with the SAP Analytics Cloud.

Thanks for reading.