Execute a Request Using a Generated OpenAPI Client

The usage of the OpenAPI clients is similar to the clients for OData. The OpenAPI clients consist of at least one API, which in turn has at least one function. What APIs and functions are available in a client depends on the service specification.

Executing a Request

The request execution always follows the same structure. You invoke a function of an API, optionally configure your request and then execute it against a destination:

const responseData = await MyApi.myFunction().execute(destination);

In the example above we invoke the function myFunction of the API MyApi without further configuration and execute it against a destination named destination. The execute method returns the response data directly as a Promise, if available. Responses without response body, result in the return type Promise<void>.

You can configure your request by setting custom headers, a custom request configuration or disabling CSRF token fetching. If you need more information than the response data, you can also get the raw response.

Passing Parameters

Often, resources are accessible under paths that require path parameters and/or query parameters and write requests often send a request body to modify resources. The clients generated by the SAP Cloud SDK OpenAPI generator require you to set the parameters that are mandatory and allow you to set those that are optional.

Path Parameters

Path parameters are always mandatory. If path parameters are present in the path pattern for a request, e.g. '/my-resource/{resourceId}', those are the first mandatory arguments in the generated function, e.g. MyApi.getMyResource(resourceId). The types of the arguments depend on the specification. Their names are always camel case and the order is determined by their occurrence in the path pattern.

Query Parameters

Query parameters can be both mandatory and optional. If query parameters for a certain API function exist, they are always the last argument of the function. Query parameters are provided as an object, e.g. if you can set a limit parameter, MyApi.getMyResource(resourceId, { limit: 10 }). The types of the parameters depend on the specification. Their names are as specified in the original OpenAPI document.

Request Bodies

Request bodies can be both mandatory and optional. The according function argument is always body and it is always between the path and query parameters, e.g. when the body is a simple object containing a title, MyApi.updateMyResource(resourceId, { title: 'My Title' }, { lang: 'en' }). If the request body is optional, you have to pass undefined, e.g. MyApi.updateMyResource(resourceId, undefined, { lang: 'en' }).

Setting Custom Headers

The SAP Cloud SDK sets all mandatory headers by default. To set additional headers or change the default values used in the headers, use the addCustomHeaders method. You can pass an object, where the key is the name of the header and the value, well the value.

MyApi.myFunction()
  .addCustomHeaders({
    apikey: 'my-api-key'
  })
  .execute(destination);

Custom headers take precedence over default headers. The example above can be used to execute requests against the sandbox systems of the SAP Business Accelerator Hub.

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 like url, headers, and others for you. In certain cases, passing additional options to axios might be required. To achieve this, you can provide a custom request configuration that will be passed down to axios. The example below demonstrates how to configure the response data type, typically used when downloading a file from an endpoint.

MyEntity.requestBuilder()
  .getAll()
  .addCustomRequestConfiguration({ responseType: 'arraybuffer' });

note

To ensure API consistency, we do not allow overriding the following options:

• method
• url
• baseURL
• data
• headers
• params

Setting a Custom Timeout

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

SDK 2.x

MyApi.myFunction().timeout(1000).execute(destination);

The value is in milliseconds and the default value is 10000 (10 seconds) This timeout applies to the request send to the target system given in the destination. If a CSRF token is fetched from the target system the timeout applies also to this call. Note that there is also a second timeout option on the destination fetch options. This relates to the calls made to SAP BTP services like destination-service or XSUAA.

Getting a Raw Response

In addition to the execute method, you can execute a request using the executeRaw method. It returns an HttpResponse, 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 httpResponse: HttpResponse = MyEntity.requestBuilder()
  .getAll()
  .executeRaw(destination);

Typical cases, where you might need to use executeRaw are:

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

Skip CSRF Token Handling

For some services, the CSRF token is not required even for non-get requests. Therefore, skipping fetching the CSRF token makes sense as a performance improvement. You can disable the CSRF token request by using skipCsrfTokenFetching() like below:

const responseData = await MyApi.myFunction()
  .skipCsrfTokenFetching()
  .execute(destination);