I was pleased to see this morning that several key SAP Cloud Platform APIs are now publicly documented and accessible for our own use.

As you’d suspect from using it, the Cloud Platform Admin Cockpit is a jQuery-based web application. Data forms are filled in by issuing REST API calls to retrieve the data to be displayed. Many of us have been chomping at the bit to be able to access these APIs for our own purposes.

As luck would have it I had two queries cross my desk this morning and both pointed to these new APIs as the solution. I’ll use those to scenarios to highlight usage and I’ll even give a walk-through demonstrating access from a REST testing application — but it might first be good to describe how to configure access for these APIs.

Authorizing Access to the Platform APIs

The Platform APIs use OAuth for authentication. The token generation process is described at this documentation web page.

• Create an OAuth Client for accessing the APIs — from your HCP Admin Cockpit – visit Security > OAuth and click on the Platform API tab; click the Create API Client button.

• Fill in the form shown below. The Description field is required but you may assign any name you like for the value. Check the Authorization Management box and ensure at least “Read Authorization” is included. Press Save.

• Your access credentials will be shown in a pop-up something like the what you see below. As the popup indicates, it is crucial that your copy and save the Client Secret value. This dialog is the only opportunity you will get to save it.

Once you have a Client ID / Secret pair, you can then make a simple OAuth call to generate an access token for all subsequent calls.

You can test this process using your favorite RESTful API testing tool.  I prefer POSTMAN. It is available as a Chrome Application. But any REST test client should suffice.

Obtaining an OAuth Access Token

The documentation shows an example of authenticating to generate an Access Token. You will submit an HTTP POST method using Basic Authentication. The username must be set to the API Client ID; the Password is the Client Secret. The POST is made to this URL — of course the landscape host value will vary based on the SAP Data Center where your account resides.

     https://api.<landscape_ host>/oauth2/apitoken/v1?grant_type=client_credentials

In POSTMAN, the request and the response will look something like this:

The access_token field in the Response contains the OAuth Bearer token that must be used for the actual API requests.  Save it.

Test a Platform API

With the access token in our hands, we can now start making Platform API calls. Let’s say you wanted to list the Cloud Platform Groups that exist in your Trial Account.  The REST API URL follows this pattern (insert your SAP ID number as shown)

https://api.hanatrial.ondemand.com/authorization/v1/accounts/<S/C/D/I/P-number>trial/groups

You must insert the access_token value into the HTTP Authorization header — the Header name will be Authorization; the value must be set to “Bearer your-access_token-goes here”. In POSTMAN, it looks something like this:

It’s worth saying the the Groups listed from my output will not match the Groups displayed in your Account, but you get the idea.

And you can repeat this process to test any APIs your like.  Currently, four classes of APIs have been made public (link):

• Authorization Management – Users/Groups/Roles and IdP mappings
• Java Application Lifecycle Management – Start, Stop, Deploy, Redeploy applications
• Monitoring – Processes, States, and Metrics
• Predictive Services – the Predictive Services APIs

A Couple of Use Cases

Application Deployment, Starting, Stopping

If you have implemented a Continuous Integration environment for Java development in SAP Cloud Platform, you probably have used the SAP Cloud Platform Maven plugin to automate testing and deployment. There is also the neo command-line tool to perform such operations.  Those are both useful to be sure, but you still might find yourself in a use case where performing such an operation via a REST API is the most effective approach — and now there’s an API for doing just that.

Automating Access Permission Auditing

SAP Cloud Platform provides several flexible ways to connect your existing enterprise user identity base directly to your Account landscape.  Moreover, that scheme allows you to map SAML Group Assertions directly over to SAP CP.  You probably know that certain administrative operations can only be performed in the HCP Admin Cockpit and that HCP Admin Cockpit access is currently only grantable to a S/C/P/I/D-user in the SAP ID Service (today). If you ever wanted to audit those access grants before the release these APIs, you’d have to manually inspect the Cockpit’s Authorizations page.  Today, though, you can now use these APIs to automate such a review process or integrate it with other systems.  Nice!

We’ve looked at a read-only example here but these APIs also support useful modification operations as well.  Check the documentation for details.

I think it is safe to say the number of public Platform APIs will continue to expand over time.  Give these a try.