Executing a Request Using a Generated OData v2/v4 Client

Once you have generated a typed OData client using the SAP Cloud SDK generator, you can use this OData client to execute HTTP requests for your service. The client provides request builders for the different types of requests and abstractions of the entity sets of the given service.

General Request Structure

On an abstract level, creating a request using the fluent API always follows the same simple structure:

import { myEntityService } from './outputDir/my-service';

const { myEntityApi } = myEntityService();
return myEntityApi.requestBuilder()
  .<requestType>(...)
  .<additionalRequestConfiguration>(...)
  .execute(destination);

If you are using an OData client, that you generated on your own, import the service function, e.g. myEntityService, from the generated service directory (my-service) within the specified output directory (outputDir). The name of the service directory corresponds to the directoryName specified in the options per service file (options-per-service.json by default).

Destructure the service to get the API of the entity you want to make requests for - myEntityApi in the example above.

Every entity API has a requestBuilder() method, that allows to chain all types of request builders that are available for this entity, e.g. myEntityApi.requestBuilder().getAll() for the getAll request type.

See the list below for details on all available request types (denoted by requestType in the example above):

OData v2

getAll

Build requests to get a list of entities (OData v2)

getByKey

Build requests to get an entity based on a key (OData v2)

create

Build requests to create entities (OData v2)

update

Build requests to update entities (OData v2)

delete

Build requests to delete entities (OData v2)

OData v4

getAll

Build requests to get a list of entities (OData v4)

getByKey

Build requests to get an entity based on a key (OData v4)

create

Build requests to create entities (OData v4)

update

Build requests to update entities (OData v4)

delete

Build requests to delete entities (OData v4)

note

Some entities do not support all the request types, which in turn won't be available through the API.

The request can further be configured by chaining additional configuration functions (denoted by additionalRequestConfiguration in the example above). All requests can be configured by setting custom request headers, custom query parameters and a custom service path.

Each request type has additional request specific configuration options, e.g. creating an entity asChildOf another entity for create requests, ETag handling for update and delete requests, as well as set operations for getAll requests and selecting properties for getAll and getByKey requests.

The last step when making a request using the SAP Cloud SDK is the request execution. Once the request is configured use the execute() method and pass a destination to it. This will automatically construct your request URL and headers, execute the request, and return a typed response if applicable.

Conversion of OData Types

OData uses the Entity Data Model (EDM) to represent values such as strings, numbers, dates, and times. Calling the execute() method by default automatically converts OData Entity Data Model (EDM) values to their respective types in JavaScript and TypeScript.

By default, the SAP Cloud SDK converts EDM types into TypeScript types as described by the following tables. This can be changed by providing custom serializers and deserializers as described here for OData v2 and here for OData v4.

For definition of the EDM data types in OData, see the v2 spec or the v4 spec of OData.

The following table describes how types are mapped by default:

EDM Type	TypeScript Type	Notes
Edm.String	string
Edm.Boolean	boolean
Edm.Guid	string
Edm.Decimal	BigNumber
Edm.Int16	number
Edm.Int32	number
Edm.Int64	BigNumber
Edm.Single	number
Edm.Double	number
Edm.Float	number	Not an actual edm type, implemented for compatibility
Edm.Byte	number
Edm.SByte	number
Edm.DateTimeOffset	moment.Moment
Edm.Binary	string
Edm.DateTime	moment.Moment	OData v2 only, precision limited to milliseconds
Edm.Time	Time	OData v2 only, does not consider time zones
Edm.Date	moment.Moment	OData v4 only
Edm.Duration	moment.Duration	OData v4 only
Edm.TimeOfDay	Time	OData v4 only, does not consider time-zones
Any other type	any

If you require the raw OData response, you can look into getting the raw response and the original request.

Setting Custom Request Headers

The SAP Cloud SDK automatically sets some necessary request headers on every request. You can specify additional custom headers using the addCustomHeaders() method:

const { myEntityApi } = myEntityService();
myEntityApi.requestBuilder().getAll().addCustomHeaders({
  apikey: 'my-api-key'
});

The keys and values of the passed object correspond with the header names and values. Custom headers take priority over automatically generated headers. Automatically generated headers are sent with lowercase header names, and custom headers keep the case they were set in. SAP Business Accelerator Hub sandbox requires a custom header called apikey. The example above shows how to add this header.

caution

Setting an authorization or apikey header (regardless of lowercase or uppercase spelling) will skip any automatic authorization header building that the SAP Cloud SDK would normally do.

Setting Custom Query Parameters

The SAP Cloud SDK adds necessary query parameters for a request based on your configuration. You can add custom parameters by using the withCustomQueryParameters() method. Custom query parameters take precedence over those created by the SAP Cloud SDK.

In the example below an additional query parameter language=en will be added to the request URL:

const { myEntityApi } = myEntityService();
myEntityApi.requestBuilder().getAll().withCustomQueryParameters({
  language: 'en'
});

note

If you want to set a query parameter in quotes (e.g. language='en') you will have to provide the parameter with quotes, e.g. { language: "'en'" }.

Setting a Custom Service Path

If a service specification contains a specification for the basePath, the SAP Cloud SDK generator generates an OData client with a default service path according to the specification (typically '/sap/opu/odata/sap/' for SAP S/4HANA services). When there is no such path defined in the specification, it can be manually set in the options-per-service.json. It can also be adjusted per request by using the setBasePath() method:

const { myEntityApi } = myEntityService();
myEntityApi.requestBuilder().getAll().setBasePath('my/custom/service/path');

This will change the base path of your request. Executing the example request above against a destination with the URL https://my.s4-system.com will result in a request against the target like this: https://my.s4-system.com/my/custom/service/path/MyEntity.

Setting a Custom Request Configuration

By default, the SAP Cloud SDK uses axios as an HTTP client for executing requests. The SAP Cloud SDK derives and configures most request options including url, headers, etc. You can provide a custom request configuration to pass additional options to axios. The example below demonstrates how to configure the response data type, typically used when downloading a file from an endpoint.

const { myEntityApi } = myEntityService();
myEntityApi
  .requestBuilder()
  .getAll()
  .addCustomRequestConfiguration({ responseType: 'arraybuffer' });

note

To ensure API consistency, the SAP Cloud SDK does not allow overriding the following options:

• url
• baseURL
• data
• headers
• params

Appending Paths to the Request URL Built by the Request Builders

Usually, the request builders construct the request URL for you automatically. However, for certain OData features like navigation properties, the SAP Cloud SDK does not provide a type-safe API that constructs the request path in a fully automated manner. For that reason, there is a non-typed API to request builders providing the capability to append additional path segments to the request URL. You have to use the executeRaw(destination) method to get results because the SAP Cloud SDK can't deserialize these responses in a type-safe way.

The example below shows how to query a navigation property from a given entity.

const { myEntityApi } = myEntityService();
myEntityApi
  .requestBuilder()
  .getByKey('123')
  .appendPath(
    '/to_SingleValueNavigationProperty1',
    '/to_SingleValueNavigationProperty2'
  )
  .executeRaw(destination);

It will build the request URL like below: https://my.s4-system.com/service-path/MyEntity(key='123')/to_SingleValueNavigationProperty1/to_SingleValueNavigationProperty2 where:

• /to_SingleValueNavigationProperty1/to_SingleValueNavigationProperty2 is the additional path that you provide from the parameters.
• https://my.s4-system.com/service-path/MyEntity(key='123') is the path of the original request URL built by the SAP Cloud SDK.

Setting Middlewares

You can specify middlewares for a request via the middleware() method on the request builder:

const { myEntityApi } = myEntityService();
const httpResponse: HttpResponse = myEntityApi
  .requestBuilder()
  .getAll()
  .middleware(myMiddlewares)
  .execute(destination);

The method accepts variable number of single elements as well as arrays. Middleware is a general concept used to add arbitrary enhancements to the request. A typical use case is to also add resilience to requests.

Getting the Raw Response and the Original Request

In addition to the execute() method, you can execute a request using the executeRaw() method. It returns an HttpResponse instance, which contains the following properties:

• status: the status code of the response
• headers: the response headers
• data: the response body
• request: the original request

Example:

const { myEntityApi } = myEntityService();
const httpResponse: HttpResponse = myEntityApi
  .requestBuilder()
  .getAll()
  .executeRaw(destination);

Typical cases, where you might need to use the executeRaw() method are:

• You need additional information about the response, like the status code or response headers.
• You need additional information about the request, like payload, method, or request headers.
• The execute() method is omitted in some request builders because the response data cannot be deserialized by the request builder.
• Debugging purposes.

• In rare cases, when the response data cannot be deserialized. This can happen when function imports use an entity type as a return type, and this entity type is shared by multiple EntitySet instances. Without further information, it is unclear which Entity should be deserialized. For those cases, you have to use executeRaw() and use the deserialize() function on the response data.

Troubleshooting

Deserialize Nested Navigation Properties

When deserializing an OData response that contains nested navigation properties, a user reported an issue about some missing navigation properties. This might happen if you don't use the object destructuring for getting multiple APIs. What you should do:

const { businessPartnerApi, businessPartnerAddressApi } =
  businessPartnerService();

What you should avoid:

const businessPartnerApi = businessPartnerService().businessPartnerApi;
const businessPartnerAddressApi =
  businessPartnerService().businessPartnerAddressApi;