Subramanian Krishnan

August 18, 2022

Working with SAP APIs

Background

Towards the end of 2020, I was building Microapps for SAP S/4HANA. It was a steep learning curve and I can say that learning to work with SAP APIs took more effort and persistence than what an average API takes. I say this because before working on SAP microapps I had spent many months building microapps for other systems like Workday, Kronos, Hubspot, and Webex to name a few.

The learning with SAP API can be categorized into 2 buckets:

  • Generic and broadly applicable

  • Specific to the use-case I was building and internal to the organization

Through this post I want to share all the learning I had in the first category (generic and non-internal). If you need to work with SAP APIs this will help save some time.

About the APIs

SAP API Hub has documentation for the different APIs supported by SAP. This covers all offerings of SAP. (The one that was relevant to our use-case was SAP S/4HANA Cloud.)

SAP supports different API styles like ODATA, SOAP and REST. Not all styles are supported for all functions. (Our integration platform required us to use JSON based APIs so we chose ODATA/REST APIs to achieve our use-cases.) Recently I got to know that SAP has added GraphQL support is also added for some use-cases.

For using the documentation portal mentioned above you can register by providing your information. After this an APIKEY will be provided which can be used to make API calls on the sandbox using the Try out option. The sandbox is READ-ONLY, provides dummy responses for illustration purposes and has rate-limits in place. Upon exceeding API rate-limits error messages are returned instead of data. Since the sandbox is read only, invoking any state changing operations return an error message.

Authentication

There are 2 types of API users/clients supported by SAP APIs:

  1. Technical users - A computer program which access the APIs for achieving some integration goals.

  2. Business users - A real/human user of a SAP system who accesses the system to accomplish a business task.

For Technical users, APIKEY based auth is supported and for Business users OAuth 2.0 is supported by SAP.

Our use-cases required reading data for all users into the cache, for which we used a Technical user with APIKEY and appropriate permissions to read data for all users into cache.

For writes which happens in the context of a human user, we used a Business user with OAuth 2.0. SAP supports the following OAuth 2.0 flows:

  1. SAML bearer assertion

  2. Authorization code

For additional references on OAuth 2.0 configuration check references section below.

ODATA Filters

OData filter expressions can be used in the APIs to select records based on a creation date or last change date. This took some time to figure out and get it working for our needs but once it worked, it made life easy. Examples below:

https://sandbox.api.sap.com/s4hanacloud/sap/opu/odata/sap/API_BILLING_DOCUMENT_REQUEST_SRV/A_BillingDocumentRequest?$filter=CreationDate ge datetime’1995-12-01T00:00:00’

https://sandbox.api.sap.com/s4hanacloud/sap/opu/odata/sap/API_BILLING_DOCUMENT_REQUEST_SRV/A_BillingDocumentRequest?$filter=LastChangeDateTime ge datetimeoffset’2020-08-04T00:00:00.0000000Z’

Custom CDS Views

Often times the data needed for a usecase comes from multiple API resources. For examples To get complete information about an Accounting Journal entry we may need the Accounting Journal API as the primary source but also need to call secondary APIs like Sales Order API and Business Partner API to get the additional data needed for the use case. A naive approach to build the integration will call the primary API and then do child/nested API calls to secondary resources.

This approach is functionally ok but may not scale well with respect to number of APIs that need to be called if the volume of data handled by the use-case is large.

An alternative and more optimal approach is such cases is using Custom CDS View in SAP HANA and exposing it as ODATA API. After creating Custom CDS view, create a communication scenario and communication arrangement using the steps documented here.

Using this newly created endpoint minimizes the number of API calls needed to get data and also the data that is exchanged between SAP and client application to the bare minimum making it super efficient.

Business Events Processing

Business Events in SAP S/4HANA are triggered as part of some Business process, for example whenever a Sales Document is Created/Changed/Deleted.

  • With this feature, upon subscription, the events are created and saved in the Outbound Event Queue in SAP S/4HANA Cloud.

  • Using OData service, you can retrieve the events from the evenet queue with your application.

Before you start using Business Event in SAP S/4HANA Cloud, please ensure:

  • Scope item 1NN is active

  • Communication arrangement for scenario SAP_COM_0121 is in place

Follow the steps detailed (with screen shots in SAP blog reference).

1. Create Subscriber Id and add BEVT as new Subscriber ID

Note: If during configure step you get error message it is likely because you don’t have the Business role: SAP_BR_BPC_EXPERT is not assigned for you. Get the role assigned and retry the configuration.

2. Enable the subscription

The list of all Events supported by S/4HANA is documented here.

For example our use-case needed Business Partner Events.

3. Business Events Queue

To access the events using ODATA API:

  • Get the base URL for the Communication Arrangement created for the scenario SAP_COM_0121

For ex. https://my305939-api.s4hana.ondemand.com/sap/opu/odata/sap/C_BEHQUEUEDATA_CDS

  • Read the events applying filters as necessary.

curl —location —request GET ‘https://my305939-api.s4hana.ondemand.com/sap/opu/odata/sap/C_BEHQUEUEDATA_CDS/C_Behqueuedata?$filter=CreationUTCDateTime ge 20210305060042’ —header ‘Accept: application/json’ —header ‘Authorization: Basic xxxx’

Note:

a. The Events API returns only information that an event occurred and not the details of the event. For getting details, additional API calls are needed to be made on the corresponding business object using its id found in the event.

b. The Events are maitained in the queue for a limited period (24 hours?) and get purged after that automatically.

Gotchas

When calling a write (POST/PUT/PATCH) operation on SAP you may get a CSRF token not valid in response. This is a known issue and SAP and the workaround is documented here.

This means before calling a write operation we need to follow these steps:

a. Call a GET on the resource with X-CSRF-Token header set to value fetch

b. The response from SAP will have the X-CSRF-Token header set

c. Extract the header from the response

d. Call the write API with X-CSRF-Token header set to the extracted value

Solution 1

The above sequence can be achieved as a custom code written on the client side.

Solution 2

Another way to solve the problem is creating an API proxy which implements the above steps and deploy it on a gateway.

Additional resources

SAP OAuth 2.0

  1. OAuth 2.0 server for AS ABAP

  2. OAuth 2.0 SAML Bearer Assertion Flow

SAP API

How to find APIs on S4 HANA

SAP API Access Setup

To enable API access for integration follow the steps for creating External API: Creating a Communication Arrangement.

While following the steps, there is a place where the Communication Scenario needs to be specified. To get the same refer to the SAP API documentation in https://api.sap.com/ for the specific API you want to enable. The Communication Scenario information is available in the details section of the API documentation.

← All stories