Skip to main content

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 you 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. 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. By default, the parameter names and values are URI encoded. Their names are as specified in the original OpenAPI document.

Header Parameters​

Header parameters can be both mandatory and optional. If header parameters for a certain API function exist, they are always the last argument of the function. Header parameters are also provided as an object, e.g. extending the example above, MyApi.getMyResource(resourceId, { limit: 10 }, { Authorization: 'my-auth-key' }). The types of the parameters depend on the specification.

info

If there are optional query parameters and required header parameters in the spec, you must pass an empty object for the query parameters if you do not intend to provide any. This is because optional parameters cannot precede required parameters. For example: MyApi.getMyResource(resourceId, {}, { Authorization: 'my-auth-key' }).

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 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.

MyEntity.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

Setting Middlewares​

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

MyApi.myFunction().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 a Raw Response​

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 httpResponse: HttpResponse = MyEntity.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.

Handling of Cross-Site Request Forgery Tokens​

To create, update, and delete requests the SAP Cloud SDK will try to send a CSRF token. Upon execution, the request will try to fetch a token first before issuing the create request. Many services require this behavior for security reasons. However, the create request will be made without a CSRF token if none could be obtained.

Skip CSRF Token Handling​

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

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

Custom CSRF Token Handling​

If you need to adjust the way CSRF tokens are fetched, you can do so by using middlewares:

  • Disable the token fetching to deactivate the default code.
  • Add a middleware to include your custom token fetching.

The SAP Cloud SDK offers a csrf middleware which allows to configure some basic options:

  • method The HTTP method used to get a token
  • URL The URL which is called to retrieve a token
  • middleware Middlewares used for the token retrieval request
const responseData = await MyApi.myFunction()
  .skipCsrfTokenFetching()
  .middleware([csrf({ url: 'https://example.com/csrf/token/url' })])
  .execute(destination);