Making a First API Call
Once you have generated a type-safe client, this is how you make your first API call. This example uses the BusinessPartner service from the SAP S/4HANA suite.
The SAP Cloud SDK does a lot of heavy lifting under the hood to take care of complexity so that you can fully concentrate on your app's logic. A detailed step-by-step guide on using a type-safe client is provided in this tutorial series.
- Destination fetching
- Handling of ETag
- Handling of CSRF token
- Serializing and deserializing the request
- And more
In this document, we focus on the proxy part and explain how proxies are handled by the SAP Cloud SDK.
What Kind of Proxies are There?
Before we get into the details, it is important to have an overview of the different proxy types. There are three possible types of proxies:
- A local proxy running on the cloud platform that connects to SAP S/4HANA On-premise systems. The proxy information like host and port are provided by the connectivity service. This proxy will be referred to as connectivity proxy.
- A proxy running in some landscape that makes requests to the internet. This proxy will be referred to as web proxy.
- A proxy which is used when your destination represents a tunnel that's created via the Private Link Service.
This proxy will be referred to as
execute() you can either give an object containing the destination name or you can configure the full destination manually.
If you provide the destination name the SAP Cloud SDK will try to look up as described here.
In productive use, the manual configuration will not be useful, but for testing, it might be valuable.
The destination object contains a field
proxyConfiguration in which you can configure a proxy.
Proxy-Authorization: 'yourAuthHeader could be basic or some bearer token',
SAP-Connectivity-Authentication field contains the
JWT issued for the user on application login.
This is mandatory if principal propagation is used i.e. identity propagation from the cloud application to the SAP S/4HANA system.
The Automatic Flow
For productive use, you do not want to include a specific proxy configuration in your code.
Here you should let the SAP Cloud SDK handle everything.
Hence, you will provide in the
.execute() method only the destination name.
This will trigger the destination lookup as described here.
The result of the lookup is a destination object which contains a property called
This property can have three values:
OnPremise is selected, it is assumed that this destination points to an SAP S/4HANA On-premise system.
In this case, you need the connectivity proxy.
The SAP Cloud SDK will request the proxy host and port from the connectivity service and make a request using this proxy.
From there the request will pass via the SAP Cloud Connector to the SAP S/4HANA On-premise system.
Internet is selected it is assumed that this destination points to something on the Internet and usually no proxy is needed.
However, if a proxy is needed to reach this destination it is configured in the following way.
The SAP Cloud SDK considers the environment variables
HTTP_PROXY is used for destinations using
http:// in their URL and
HTTPS_PROXY for the ones using
https is the default protocol if the protocol is not set in the URL field of the destination.
The value of the two proxy variables is just a simple string following this pattern:
The user and password are optional and if they are left out no authentication header is added.
The protocol is also optional and the default value is
http since most proxies do not use an encryption layer for communication.
The default for the port is
Example of valid values would be:
https://some.host.com:1234 -> will use 443 as default
some.host.com:1234 -> will use http as default
some.host.com -> will use http and 80 as default
If you use any special character in your username or password you need to encode them using percent encoding
Since environment variables are a global setting, it might become necessary to exclude some destinations from using the proxy.
This is possible using the
NO_PROXY environment variable.
NO_PROXY variable contains a list of comma-separated URLs for which no proxy is used.
Currently, wild cards like
* are supported in the list.
PrivateLink is selected we use the same flow as we do for proxy type
A Word on the Used Libraries and Implementation Details
The SAP Cloud SDK uses axios to execute
In principle axios should support web proxies based on the environment variables.
However, we found that the request URL using a proxy was not correctly constructed and for the connectivity proxy, an entry point was necessary anyhow.
Hence, the SAP Cloud SDK switches off the built-in proxy handling by axios completely by using the following axios request configuration.
If a proxy becomes necessary or is configured by the discussed environment variables the SAP Cloud SDK builds directly the
"httpAgent": httpProxAgent || new http.Agent(),
"httpsAgent": httpsProxyAgent || new https.Agent()
This adds them to the axios configuration. The agents contain the proxy configuration. The standard http and https agents are used.