API-related Information - SAP S4HANA

This article contains the following information related to APIs.

• Pagination Info
• 3X-CSRF Token
• Handling Errors
• Connector BP Tasks and Schema Reference

Pagination information

OData V2

If more records match the query filter criteria for an OData V2 API, the OData standard provides a '__next' link in your query response if there are more results in the database. Use the value of the '__next' link property with a new GET request to return the next page of data.  An example:

"__next": "https://[HOST]/sap/opu/odata/sap/API_PRODUCT_SRV/A_Product?$skiptoken=100"

OData V4

If more records match the query filter criteria for an OData V4 API, a @odata.nextLink property will be returned with the results. Use the value of the @odata.nextLink property with a new GET request to return the next page of data. An example:

"@odata.nextLink": "/sap/opu/odata4/sap/api_product/srvd_a2x/sap/product/0002/Product?$skiptoken=100"

3X-CSRF Token

SAP Gateway protects modifying requests such as HTTP POST against cross-site request forgery (CSRF) attacks. Normally, this requires the client to provide a CSRF token along with the modifying request. The client can obtain this token with the first non-modifying call to the service by setting the HTTP header X-CSRF-Token to the value Fetch. A CSRF token is returned by the server in the same response header. The client can then use it for modifying requests using the header X-CSRF-Token.

Since the content upload service supports HTTP POST only, the only non-modifying request that can be used to obtain the CSRF token is HTTP HEAD. The ideal flow is like the following:

1. The client application sends a GET request with header X-CSRF-TOKEN: Fetch (this is usually sent in the $metadata or a simple service document request).
2. The server then responds with 200 OK and response header: X-CSRF-TOKEN: <tokenValue> and one or more Set-Cookie headers.
3. The client has to store this token and all the cookies in the Set-Cookie response header (the cookie here identifies the HTTP session) and send in every modification request ( POST, PUT, PATCH, MERGE, DELETE) throughout its session. When the session renews the CSRF token has to be renewed as well, by requesting a token again.
4. The server will check this token and the session ID cookie(s) and if they’re valid and matching, it’ll process the request. If at least one of them is invalid or expired then the server will respond with 403 Forbidden, with response header: X-CSRF-TOKEN: Required, with response body: “CSRF Token required”
5. The client has to automatically send a new GET request with X-CSRF-TOKEN: Fetch and retrieve the new token from the response header.

Requesting the X-CSRF-Token is handled internally in SAP S/4HANA Cloud Connector. 

The successful scenario would look like this:

The scenario where it fails once and the client has to re-request the CSRF token would look like this:

Error Handling

In case SAP S/4HANA Cloud Connector Bps i.e. API call is successful (returns status code btw 200 & 300) , the business process task will pass and return response payload (in Studio’s Admin Console perspective, in Auditor View the task is marked as completed)

Or

In case SAP S/4HANA Cloud Connector Bps i.e. API call has failed (any response status code not between 200 & 300) bps task will fail without returning any response payload (in Studio’s Admin Console perspective, in Auditor View the task is marked as failed & error payload returned from SAP S/4HANA Cloud and stack trace are logged)

Or

In case SAP S/4HANA Cloud Connector Bps i.e API call execution fails (which can be an internal error such as a payload parse issue) task will fail without returning any response payload (in Studio’s Admin Console perspective, in Auditor View the task is marked as failed & stack trace is logged). 

The user can also view and filter error logs related to SOAP web services, and OData services using the SAP Fiori apps like - SOAP Error Log, and OData Error Log to Get a comprehensive overview of failed communications. For more information, refer to the SAP documentation.

Note - In the case of executing a SOAP synchronous service, even if the business process task is executed successfully, the operation might not be successfully processed. Kindly refer to the business documentation of the relevant service, to identify the unsuccessful case from the service error response.
For example, the business documentation of the Journal Entry - Post (Synchronous) service highlights that if the journal entry isn't posted successfully, a zero is returned in the parameter AccountingDocument within the service response. In such cases, the business process task will pass and return a response payload, but the user has to handle such error scenarios in the implementation project itself.

Connector Business Process Task and Schema Reference

NOTE: Business Process and Schema will be based on the services selected during connector creation.

Only a few services that are part of Order to Cash Flow are listed here.