openSAP Modernize Integration with SAP

Integration Suite

Exercise

Week 3: API and Event-Based Integration

API Management

PUBLIC
INTRODUCTION
Welcome!
In this exercise, we will experience with the API Management capability of SAP Integration Suite.

Before you start

This openSAP course is very popular, and we welcome thousands of participants. The exercise described in
this document will be performed by hundreds of participants in parallel, using production tenants with shared
resources in a shared SAP Business Technology Platform (BTP) account. This means a few simple things:

1. Use the tenant that we provide only for this exercise, and not for anything else. For further
exploration of API Management, use a free BTP trial account or a Free Tier tenant.
2. Do not share any private or personal information such as your name, email address or affiliation.
3. Please strictly follow the instructions, regarding the naming conventions you will use to name the
artefacts you will create. This ensures that you will be able to successfully complete the tasks,
without clashing with other participants.
4. Other artefacts, created by other participants, will appear in your shared account. Do not access or
delete these artefacts. Please respect the rules and allow others to have the same learnings as you.

We have done everything to make this experience enjoyable. Your OpenSAP account was pre-configured by
a competent technical BTP administrator, and you already have all the roles and definitions you need to
complete this exercise.
The story
You are the API Administrator of BestRun, an international company.

One of your clients has asked you for an API to access the credit rating of BestRun’s worldwide
suppliers. These suppliers are maintained as “Business Partners” in your corporate SAP
S/4HANA system, but without credit rating information. Luckily, your colleague has written a
CAP-based application that extends the SAP S/4HANA partner data with credit ratings.

Your task is to design a secure and easy-to-use API for your client.
What we will do
In this exercise we will perform the following steps:

1. Design a custom Graph model extension.

2. Create a business data graph
3. Use the Graph Navigator
4. Create an API proxy for the API of the data graph
5. Use Postman to test the API proxy.
6. Add an OAuth policy template to the API proxy.

Getting started
As in other exercises in this OpenSAP course, you will log in
to the SAP Integration Suite application on the Business
Technology Platform. Use your SAP id and the “Tenant
Booker” URL to book a tenant:

https://techedtenantbookerapplication-
ad5b9d48b.dispatcher.hana.ondemand.com/index.html

Once approved, you will see a password and several other credentials that we will need in later steps for our
exercise. You can leave the browser tab open and refer to it later, or you can “copy-paste” the credentials
into a scratch pad. At any time, you can also rerun the “tenant Booker” link to re-display your credentials.

Note that these credentials are private to you – please do not share them.

2
LET THE FUN BEGIN
Step 1 – Design a custom model extension
Suppliers are maintained in the SAP S/4HANA system, and accessible via the A_BusinessPartner API.

We don’t want to give our client direct access to this API. Firstly, the
credentials are highly confidential, and unauthorized usage might impact
our business. Secondly, the A_BusinessPartner entity is very complex
with well over a hundred attributes (see illustration), which may overwhelm
our client, who only needs the partner address and credit ratings. Thirdly,
and most importantly, the credit ratings of the partners are managed in a
separate CAP application on BTP.

Our goal is to provide the client with a simplified view of the partners, their
location, and their credit ratings, via a single API, using the Graph
capability of API Management and further secured by an API proxy.

The simple CAP financials application written by our colleague, has a RATINGS
entity that matches the business partner on its key (BP), and looks like this, based
on a very simple corresponding CDS entity specification.

The financials application is poorly secured by basic authentication and runs on

BTP. Again, we do not want to provide direct access to it from our client, with whom
we would have to share the user/password to the application. And, the client would
have to learn how to make multiple queries to two different applications, and then combine the data, just to
get the information they need.

So how do we solve this?

The Graph feature of API Management supports the concept of custom extensions, technically a set of one
or more entities with views on one or more underlying data sources. We will design such a custom entity.

This new custom entity will present the location of the partner from the A_BusinessPartner entity in SAP
S/4HANA, and the credit ratings from the RATINGS entity in the CAP application. We will call it RatedPartner
within a custom namespace called bestrun. Take a look at the following illustration.

The easiest way to develop such an extension entity is to use the powerful graphical extension editor.
Unfortunately, this editor was not yet available at the time we put this course together in mid-2023, and so,
instead, we will define the extension specification as a JSON specification, as seen in the box below.

3
 {
"version": "1.0.0",
"entity": "bestrun.RatedPartner",
"label": "Rated Partner",

"sourceEntities": [
{"name": "my.custom.RATINGS"},
{"name": "sap.s4.A_BusinessPartner","join": [["BP", "BusinessPartner" ]] }
],
"dicts": { "map": { "excellent": "9", "very good": "8", "good": "7", "acceptable": "6", "at risk": "5" } },

"attributes": [
{ "name": "id", "source": [ "BP" ], "key": true },
{ "name": "name", "source": [ "BusinessPartnerFullName"], "sourceEntity": "sap.s4.A_BusinessPartner", "type": "String" },
{ "name": "isActive", "source": [ "IsMarkedForArchiving"],
"sourceEntity": "sap.s4.A_BusinessPartner", "transform": "negation", "annotations": { "readonly": true, "description": "can be used" } },

{ "name": "location[]", "source": [ "to_BusinessPartnerAddress[]" ], "sourceEntity": "sap.s4.A_BusinessPartner" },

{ "name": "location[].city", "source": [ "to_BusinessPartnerAddress[].CityName"], "sourceEntity": "sap.s4.A_BusinessPartner" },
{ "name": "location[].country", "source": [ "to_BusinessPartnerAddress[].Country" ], "sourceEntity": "sap.s4.A_BusinessPartner" },

{ "name": "rating.Moodys", "source": [ "M" ], "annotations": { "description": "Moody's credit rating" } },

{ "name": "rating.Fitch", "source": [ "F" ], "annotations": { "description": "Fitch Ratings' score" } },
{ "name": "rating.StandardPoor","source": [ "SP"], "annotations": { "description": "Standard&Poor's global credit rating" }},
{ "name": "rating.totalScore", "source": [ "map", "Avg"], "transform": "dict", "type": "String",
"annotations": { "description": "consensus credit score" }}
]
}

You should be able to understand how this works. We define the new entity bestrun.RatedPartner, and the
two source entities it uses. Then, we define a list of attributes and their derivation from corresponding source
attributes, using “transform” functions. You can study the detailed specification in the Graph documentation.

Carefully copy the text in the box and save it into a file on your computer, with file extension of json.
For instance: my-ratedpartner.json. Make sure you didn’t drop anything during the copy.

OR

This JSON specification is available as a file named my-ratedpartner.json in the “Additional

Download” of week 3. Upload it and save the file into a folder on your computer.

4
Step 2 – Create a Business Data Graph
From the tenant booker application, click on the “Tenant URL for SAP Integration Suite” link to log in with
your user and password, and to access the SAP Integration Suite application in your account.

Click on the top-left hamburger, so you can see the menu of the SAP Integration Suite on the left.

Then, select Design => Graph from the menu.

You see the Graph wizard. There may be several data grpahs already created by other course participants.
Just ignore them.

First, let’s upload the my-ratedpartner.json extension specification we saved in step 1:

Click on the Model Extensions tab.

Again, you may see extensions created by other participants. Ignore them.

Click Create to add yours.

Enter a name for your new model extension. The name must be unique and therefore must start with uNNN,
where NNN is your tenant user id. For example, if your tenant-user is “user 311”, you can name the model
extension u311-ratedpartner. Upload the file from step 1, click Create and then Close, to complete to
process.

5
Next, go back to the Business Data Graphs tab, and start the wizard, Create => New business data graph.

Enter an ID for the data graph. This name must be unique, and therefore must start with uNNN, where NNN
is your tenant user id. For instance, if your tenant-user is “user 311”, you can name the data graph u311-rp.

Note the resulting Graph URL. The data graph ID is the last part of this URL.

Click on Next and check the two data sources we will use for our data graph. Do not check PO_POP_DIR,
which is for a different exercise.

6
Click Next and in the next step select the model extension specification that you just uploaded. Click Next
again and wait about 15 seconds. The Graph system is checking your data sources, discovering and
connecting entities, and creating a data graph configuration. When complete, you will see the configuration.
If you made a mistake, check the logs, and try again.

The configuration can be fine-tuned for complex use cases and landscapes, but
we just click on Create and wait about two minutes, for the system to instantiate
and run the data graph. During this time, you will see a status of processing.

When the status turns to “Available”, the URL is live, and we are ready to check
it out, using the Graph Navigator.

7
Step 3 – Use the Graph Navigator

There is little “keypad” on the right of the top-bar. Click it, and
then select Graph Navigator.

When the Navigator comes up, select the data graph you just
created, then select the bestrun namespace, and within that the
RatedPartner entity which we defined. You can see the
documented schema and an example.

The Graph navigator is connected to live data, the example comes from a real system.

Now, click on the Try Out tab, and click Run to see how to execute an OData query. By changing the query,
you can get powerful results. For instance, you could try the following queries (don’t copy paste – type these
in and be impressed by the OData auto-completion feature of the Graph Navigator ! $):
#
"

/bestrun/RatedPartner?$top=10&$expand=location&$select=name,rating

/bestrun/RatedPartner?$top=30&$filter=rating/Moodys eq 'AAB'

Note that the data graph also includes other entities (in other namespaces) in the data graph, and you can
still access these other entities, using the same Graph API and URL.

When done, you can close the browser tab.

8
Step 4 – Create an API proxy
As we saw, the Graph API is a powerful abstraction, providing access to the underlying data with one API.
But what if we want to really limit our client to only use the new RatedPartner abstraction?

In the following step, we will add an API Proxy to the Graph API, which will have two purposes: one, it will
limit access only to the new RatedPartner URL, and two, it will limit access to only three calls per minute.

You should still be on the Graph page in the SAP Integration Suite (if not, click Design => Graph). Find the
data graph we just created and played with in the list. Copy the URL of that data graph.

From the menu, click Design => APIs and then Create.

A form pops up.

The form must be filled in as follows:
• Select the “URL” radio button.
• Enter the data graph URL you just copied in the target URL; then add /bestrun to the end of the URL.
• Name the API proxy. This name must be unique, and therefore must start with uNNN, where NNN is
your tenant user id. For instance, if your tenant-user is “user 311”, you can name the API proxy
u311-proxy.
• Copy the same name into the title and API Base Path fields.

• Click Create.

9
 • Click Save.

Note the API proxy URL at the top of the screen (including “prod.apimanagement”, ending with the API base
path that you configured just now. Most customers would actually create a nicer-looking “vanity” URL (e.g.,
api.bestrun.com/u311-proxy) for their API proxy, completely hiding the “internal URLs” behind a firewall. This
is beyond this exercise.

Now let’s add a quota policy to our API Proxy. Click on Policies, and on Edit on the Policy Editor.

Select the ProxyEndPoint, and then its Preflow. Now, on the right, scroll until you find the Quota Policy.

Click on the plus (+) and give it a name, e.g. my-quota and Add. This will add the policy to API Proxy.

10
At the bottom you will find the policy configuration:

The default policy allows a count of two calls per one (1) minute. Go ahead, change the allow-count to 3. We
will test this later.

Now, click Update, and Save.

Note that the API proxy is not yet deployed. Select the ellipsis (…) on the right, and Deploy. Done!

If you now try to click on the API proxy URL (go ahead), the call will fail. Why? The API Proxy, by default,
propagates the identity and authentication credentials from the caller to its target URL, here the data graph.
The data graph expects an OAuth 2.0 authentication token, and since we just clicked on a link, this fails.

We will check this out further in the next step.

11
Step 5 – Use Postman to test the API Proxy

In this step we will use Postman (or any other OAuth 2.0 supporting test tool) to obtain a token with which we
will call the API proxy. If you are not familiar with Postman, you can download it from
https://www.postman.com/downloads/ . Open a new top-level tab with the +, and you are in business.

Within the Postman tab, go to the Authorization tab, and enter the credentials which you saved at the
beginning of this exercise, as illustrated below:

Click on Get New Access Token. If all went well, you will get a new token, Click Proceed and Use Token.

Now, enter the URL of the API proxy where you see GET (not POST) at the top of screen. But remember,
that is the URL of the bestrun namespace. You need to append, for example, /RatedPartner?$top=1.

Click Send. If all went well, you will now see:

Congratulations!

Oh: one more thing: repeat clicking Send a few times.

Cool, no?

Step 6 – Add an OAuth policy template

What if we want to enable “anonymous” and unauthenticated (but still carefully controlled) access to our data
graph, which still expects an OAuth 2.0 token?

12
For this, we are going to use a Policy Template, called “Cloud_Platform_Connectivity”. You can find this
policy template, and many, many more on the SAP Business Accelerator Hub. The documentation for the
template we are using can be found here: https://hub.sap.com/policytemplate/Cloud_Platform_Connectivity

Go back to Design => APIs in the SAP Integration Suite application.

Select your API proxy from the list of APIs.
At the top, click Policies and on the Policy Editor, click Edit.

Click on Policy Template => Apply in the top corner.

Check the Cloud_Platform_Connectivity template and Apply.

The policies from the template now appear in the “picture”.

We now need to insert the client ID and client secret in the getcredential policy, and the URL used to grant a
token, in the getoauthtoken policy.

Start with the the getcredential policy. Select this policy in the picture. The configuration shows at the bottom
of the screen. Insert the client ID and client secret from the scratchpad of credentials you saved at the
beginning of this exercise.

Then select the getoauthtoken policy. Change the access token URL as follows:

13
Note carefully: add /oauth/token?grant_type=client_credentials to the end of the access token URL.

Ok. We are almost done…

Click Update, then Save, and then Click to Deploy the changes.

Now, enter the URL of the API proxy in a browser tab (remember? You can find the URL in the list of API
proxies). Remember to append, for example, /RatedPartner?$top=3, in order to see a bit of data.

With the additional policies from the policy template, the API proxy now handles the OAuth protocol on behalf
of the caller, and the data graph is available for “anonymous” usage.

Try to refresh the page. After 2 or 3 times (depending on how you configured the quota policy), access will
be denied.

That‘s it! You made it to the end!

Enjoy the rest of the OpenSAP course!

14
Coding Samples
Any software coding or code lines/strings (“Code”) provided in this documentation are only examples and are not intended for use in a production system environment. The Code is only intended to better
explain and visualize the syntax and phrasing rules for certain SAP coding. SAP does not warrant the correctness or completeness of the Code provided herein and SAP shall not be liable for errors or
damages cause by use of the Code, except where such damages were caused by SAP with intent or with gross negligence.

www.sap.com/contactsap

© 2021 SAP SE or an SAP affiliate company. All rights reserved.

No part of this publication may be reproduced or transmitted in any form or for any purpose without the express permission of SAP SE or an SAP affiliate company.

The information contained herein may be changed without prior notice. Some software products marketed by SAP SE and its distributors contain proprietary software components of other software vendors.
National product specifications may vary.

These materials are provided by SAP SE or an SAP affiliate company for informational purposes only, without representation or warranty of any kind, and SAP or its affiliated companies shall not be liable
for errors or omissions with respect to the materials. The only warranties for SAP or SAP affiliate company products and services are those that are set forth in the express warranty statements
accompanying such products and services, if any. Nothing herein should be construed as constituting an additional warranty.

In particular, SAP SE or its affiliated companies have no obligation to pursue any course of business outlined in this document or any related presentation, or to develop or release any functionality
mentioned therein. This document, or any related presentation, and SAP SE’s or its affiliated companies’ strategy and possible future developments, products, and/or platform directions and functionality are
all subject to change and may be changed by SAP SE or its affiliated companies at any time for any reason without notice. The information in this document is not a commitment, promise, or legal obligation
to deliver any material, code, or functionality. All forward-looking statements are subject to various risks and uncertainties that could cause actual results to differ materially from expectations. Readers are
cautioned not to place undue reliance on these forward-looking statements, and they should not be relied upon in making purchasing decisions.

SAP and other SAP products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of SAP SE (or an SAP affiliate company) in Germany and other
countries. All other product and service names mentioned are the trademarks of their respective companies. See www.sap.com/trademark for additional trademark information and notices.