Technology Blogs by SAP
Learn how to extend and personalize SAP applications. Follow the SAP technology blog for insights into SAP BTP, ABAP, SAP Analytics Cloud, SAP HANA, and more.
Showing results for 
Search instead for 
Did you mean: 
<< Japanese version is here >>

1. Overview

This blog will be the third part of the blog series on How to extend SAP S/4HANA on SAP Cloud Platform, which will be the usage of the API of SAP S/4HANA from SAP Cloud Platform.

  1. Overview of SAP S/4HANA extension development on SAP Cloud Platform

  2. How to find SAP S/4HANA API

  3. How to use SAP S/4HANA API    << Here

  4. If API does not exist

  5. Event integration with SAP S/4HANA

In the previous blog, we explained how to find API of SAP S/4HANA, how to search OData and SOAP API in SAP API Business Hub, and how to search BAPI in BAPI Explorer. In this article, we will focus on what tools and methods are available for using these APIs and especially describe the SAP Cloud SDK.

In addition, according to the extension guideline ( SAP Note 2920697 ) of SAP S/4HANA Cloud EX (former STE) updated on May 1, 2020, the extension way using APIs and events published in SAP API Business Hub has become a high priority.

2. Main API usage patterns from applications

There are mainly the following development patterns that use API in the extended development of SAP S/4HANA.

In the above pattern, the correspondence to each API is as shown in the table below.

SAP Cloud SDK Cloud Platform Integration SAPUI5
OData Yes (VDM) Yes (OData Adapter) Yes (OData Model)
SOAP Yes (VDM) Yes (SOAP Adapter) Yes (XML Model)
BAPI Yes (VDM, only Java) Yes (RFC Adapter) No
IDoc No Yes (IDoc Adapter) No

The above three patterns are not options in the same row but have different development layers, so we need to use them according to the development requirements and choice of development technology. Among them, SAP Cloud SDK is a tool that can call SAP S/4HANA API very efficiently in the development of server-side applications. In the next chapter, we will introduce this SAP Cloud SDK in detail.

3. SAP Cloud SDK

SAP Cloud SDK consists of Java/JavaScript (Typescript) libraries and CI/CD Jenkins pipeline templates that make extended development of SAP S/4HANA, SAP Success Factors, and etc. more efficient.

The library can be used in any project of Java or Node.js, and it can be used in combination with frameworks such as Spring Boot for Java and Express or Nest.js of Node.js for JavaScript. Therefore, the developer can select the development language/framework that they are familiar with and then apply the SAP Cloud SDK library to the linking part with the SAP solution. Of course, it can also be integrated with SAP Cloud Platform's own development framework, SAP Cloud Application Programming Model (CAP).

In addition, SAP Cloud SDK is a wrapper library of OData, so developers can efficiently develop applications without being aware of actual OData. (Calling OData API inside SAP Cloud SDK)

A lot of information about how to use SAP Cloud SDK is introduced step by step in SAP Tutorial Navigator. In this chapter, we will focus on the information that is fundamental to learning and the advantages that are easy to understand.

3.1 VDM (Virtual Data Model)

At the heart of the SAP Cloud SDK is a virtual data model called VDM. I think it would be hard to imagine with this name alone, but VDM is a class of OData metadata (API design document) of SAP S/4HANA. For example, the metadata of OData of Business Partner is as follows. (Excerpt)

The above is a part of the items, but it will be a daunting thought to define these items on the application side that calls this API. On the other hand, SAP Cloud SDK provides the items (properties and data types) that make up the Business Partner API as classes as shown below. (The following is the API documentation of SAP Cloud SDK for JavaScript )

In other words, thanks to VDM being provided, you can handle the huge number of items (properties and data types) required to use the Business Partner API in the source code without having to define your own. In addition, since the available method/property is code-completed when coding, it contributes to the improvement of development efficiency by reducing description mistakes. If you do not use SAP Cloud SDK, you will have to define the necessary items yourself from the Business Partner API, so I think this difference is significant. Below is an example of coding in VS Code using the SAP Cloud SDK for JavaScript.

Is the image of VDM gradually rising? The VDM corresponding to the above Business Partner and other abundant OData APIs is prepared as a package of Node.js in the Javascript version, so you can easily use it by importing it.

3.2 Authentication abstraction

By using the SAP Cloud SDK, you can easily implement authentication/authorization when calling the API.

Of course, to call the API, you need to authenticate to the API providing system. In the case of system to system integration, there are many cases where authentication is performed using a fixed ID like the system user, so it is not difficult. On the other hand, in the case of applications used by end-users, in addition to authentication, it is necessary to consider data access (authorization) according to the user's role. This authorization depends on the privileges assigned to the user ID on the SAP S/4HANA side. In other words, in the case of Side-by-Side extension, it is necessary to access (SSO) SAP S/4HANA and call the API with the user who matches the user who logged in to the application on SAP Cloud Platform. I think it is difficult to code this by yourself to build a mechanism, but as an authentication function that realizes this, Principal Propagation for on-premises through SAP Cloud Connector and SAML Bearer Assertion for the cloud are provided by SAP Cloud Platform. (Destination service manages this system connection centrally.)

And, by using SAP Cloud SDK, you can link with this Destination service, so just specify the destination name in the source code as shown below (destinationName), and the coding for authentication is completed. Regardless of the authentication type, it is a very convenient function that you only need to specify what you set in the Destination service on the source code side.
function getBusinessPartners(){
return BusinessPartner.requestBuilder()
destinationName: 'S4HANA1909-Dev' // the name configured Destination service.

* The above is a simple example of using the Business Partner API to acquire all data without narrowing down the items.

3.3 CRUD processing

CRUD (Create/Read/Update/Delete) process to call SAP S/4HANA API is also simple. The basic form is to use the requestBuilder method from the imported SAP Cloud SDK class (BusinessPartner and BusinessPartnerAddress in this example). There is no Delete process in BusinessPartner class, so use the BusinessPartnerAddress class.

Also, if you are familiar with OData, it may be smooth to check which class is used from each VDM module of SAP Cloud SDK by checking the original OData entity in SAP API Business Hub. (The entity name of OData and the class name of SAP Cloud SDK are similar)

In the following, we will explain the points of CRUD processing by referring to “Build an Address Manager with the SAP Cloud SDK's OData Virtual Data Model” of Tutorial Navigator. (The source code has been simplified to make it easier to understand)

3.3.1 Read

In query processing, use the getAll method. In addition, the following methods such as SQL query, which is a feature of OData, can be used in combination. (For details, see this API guide )

  • select: Specify the item you want to get (equivalent to $select of OData)

  • top: Specify the number of records you want to get (equivalent to $top of OData)

  • filter: Specify the acquisition condition (equivalent to SQL Where clause or OData $filter)

  • orderBy: Specify sort order (equivalent to $orderby of OData)

The method is to describe them in the form of a method chain that connects them with "." (dot).
// Import "BusinessPartner" class from Business Partner Service VDM of SAP Cloud SDK.
import { BusinessPartner } from '@sap/cloud-sdk-vdm-business-partner-service';

.getAll() // Read method
.top(10) // Get first 10 records
.select( // Get selected fields
.filter( // Specify BP category as condition
.execute({ // Specify the destination name of Destination service for authentication. (You can write URL,ID,Password directly)
destinationName: 'S/4HANA1909-Dev'


3.3.2 Create

The registration process uses the create method. The data to be registered will be passed as a parameter to this create method. This parameter is instantiated using the builder method of the imported BusinessPartner class.
import { BusinessPartner, BusinessPartnerAddress } from '@sap/cloud-sdk-vdm-business-partner-service';

// Instanciate data for new entry using builder method of BusinessPartner class
const businessPartner = BusinessPartner.builder()
BusinessPartnerAddress.builder() // "Deep create" is also possible to register the address information of related entities with single API call.

// Execute create processing using requestBuilder method.
.create(businessPartner) // Pass the data for new entry as parameter
destinationName: 'S/4HANA1909-Dev'

As with other Update and Delete processes, when updating data by using OData normally, the CSRF token is first acquired, and the update process is performed after adding the token to the HTTP header. (Security measures for CSRF) On the other hand, SAP Cloud SDK automatically performs such processing, so the implementation time is reduced.

3.3.3 Update

The update process uses the update method, but the usage is almost the same as the registration process. OData has a version identifier (ETag) so that if there is a difference between the time of data acquisition and the time of updating, it will not be updated with old data, and if the versions do not match, the processing request will be rejected. VDM handles this version identifier automatically, but by adding the ignoreVersionIdentifier method, version comparison can be ignored and the update process forced.
import { BusinessPartner } from '@sap/cloud-sdk-vdm-business-partner-service';

// Instanciate data for update entry using builder method of BusinessPartner class
const businessPartner = BusinessPartner.builder()
// Difine data (omitted)

// Execute update processing using requestBuilder method.
.update(businessPartner) // Pass the data for update entry as parameter
.ignoreVersionIdentifier() // (option) When forcibly updating without comparing with the version identifier of backend OData
destinationName: 'S/4HANA1909-Dev'


3.3.4 Delete

The delete process uses the delete method. Pass the ID of the target entry in the parameter. In the Delete method of BusinessPartnerAddress in the example below, you need to specify the business partner ID and address ID.
import { BusinessPartnerAddress } from '@sap/cloud-sdk-vdm-business-partner-service';

// Difine Business Partner ID and Address ID you want to delete
const businessPartnerId = "1";
const addressId = "2";

// Execute delete processing using requestBuilder method
.update(businessPartnerId, addressId) // Pass the data for delete entry as parameter
destinationName: 'S/4HANA1909-Dev'


3.4 Other useful functions

In the above, I mentioned basic CRUD processing, but in OData, you can use Batch requests that execute multiple CRUD processing in single POST processing. The SAP Cloud SDK also supports this Batch request. Also, the above content was a code example for the SAP Cloud SDK for JavaScript, but the Java version can do the same. In addition, the Java version may be preceded by the release of the SAP Cloud SDK itself, and there are many features that the JavaScript version does not have. For example, a class called BAPIRequest (BAPIQuery in Ver2.x) that can call BAPI instead of OData is also provided.

3.5 SAP Cloud SDK Client

The SAP Cloud SDK for JavaScript also has a Node.js package called the SAP Cloud SDK Client that provides useful features for getting started with development projects. After installing the package as shown below, creating a project will also create a basic project directory and add the dependencies required to use the SAP Cloud SDK. You can also generate an App Router that provides the authentication function for Cloud Foundry applications.
$ npm install -g @sap-cloud-sdk/cli
$ sap-cloud-sdk init project-name

If you execute the above initialization command in an empty directory, you will be asked if you want to initialize with Nest.js base, but we recommend that you do it with Nest.js base. Nest.js is...

  • TypeScript Node.js framework (open source)

  • TypeScript is a superset of JavaScript with class-based object orientation, so it is suitable for server-side JavaScript application development.

  • SAP Cloud SDK is also developed with TypeScript

  • Since it is based on Express, which is a general framework for Node.js, it is possible to use the rich features of Express.

There are various features other than the above, but the learning content of SAP Cloud SDK published by SAP is also guided by the Nest.js-based project, so I hope you can catch it up as well.

In the case of SAP Cloud SDK for Java, by specifying Maven Archetype, it is possible to generate project templates such as Spring and TomEE that incorporate SAP Cloud SDK.

4. Additional information

SAP Cloud SDK Official Page

Entrance for all information. You can access information such as overview information, how to get started, release notes, API guides, etc.

SAP Cloud SDK Official Tutorials, Community & Resources

SAP provides a wealth of step-by-step tutorial content and SAP Blog information about the SAP Cloud SDK.

Build an Address Manager with the SAP Cloud SDK’s OData Virtual Data Model (SAP Tutorial Navigator)

This tutorial is referred to in Chapter 3.3 CRUD processing of this blog. I recommend you this is comprehensively introducing the SAP Cloud SDK development using OData of SAP S/4HANA from the basics.


The above is the API usage of SAP S/4HANA extension on SAP Cloud Platform. How was it? As I touched on at the beginning, there are different ways to use the API depending on the scenario such as Cloud Platform Integration as well as SAP Cloud SDK, so I would like to introduce it in the future.

Next blog post, we will look at the Event Integration using SAP Enterprise Messaging, so please look forward to it.