ETag Handling

ETag handling in SAP Gateway.

SAP Gateway offers generic support of ETag (conditions) handling. ETags or entity tags are part of the HTTP protocal. They are header fields that help to determine changes of a resource and can be used in caching scenarios so that redundant data transfer can be minimized. ETag handling is one of several mechanisms that HTTP thus provides for Web cache validation and which allows a client to make conditional requests. OData uses HTTP ETags for optimistic concurrency control.

ETag support in SAP Gateway is provided in both the SAP Gateway hub system and in the SAP Business Suite backend system. Consequently, both hub and backend applications can enhance or modify the generic check. Backend operations can also override the generic conditional handling for data modification requests, such as PUT, MERGE and DELETE in the backend system.

A few special considerations apply for ETags:
  • When retrieving an entry, the system returns an opaque ETag value.
  • When getting several entries in a feed, the ETag value is included as metadata in the entry itself.
  • When retrieving a single entry, the ETag is returned as a response header called ETag as defined by HTTP. The server can choose to also include it in the body as they would do for feeds for consistency.
  • During processing of POST, PUT, and MERGE the system should compute a new ETag and return it in a response header, regardless of whether the response has a body with the actual entry information.
  • When issuing a PUT, MERGE or DELETE request, clients need to indicate an ETag in the If-Match HTTP request header. If it is acceptable for a given client to overwrite any version of the entry in the server, then the value "*" may be used instead. If a given entry has an ETag and a client attempts to modify or delete the entry without an If-Match header servers should fail the request with a 412 response code.

OData servers will often use weak ETags as a way of indicating that two resources may be semantically equivalent but a particular request may see a different representation of it.

The following interfaces provide methods for ETag handling:

Function Imports as Actions

If you want to use a function import as an action, you would usually choose the OData eTag handling. For the HTTP methods PUT and POST for function imports (hence actions), the conditional handling has to be implemented by the application developer in the data provider class DPC. To do this, overwrite method /IWBEP/IF_MGW_APPL_SRV_RUNTIME~EXECUTE_ACTION. The conditional settings from a client are available via import parameter IO_TECH_REQUEST_CONTEXT of method GET_CONDITIONAL_INFO.

Proceed as follows in these cases:
  • If the conditional information is initial, the client has not set any If-Match or If-None-Match headers.

    If conditional handling is required by the application, the response must be an HTTP code 428 (precondition required).

  • If the specified condition is not initial, the application has to check the client-provided conditions matching with the calculated eTags.

    If the calculated eTag and the eTag provided by a client do not match, the application must respond with an HTTP code 412 (precondition failed).

  • If the provided eTag from the conditions matches with the calculated eTag, the processing can continue.

What does the SAP Gateway Foundation runtime check on conditional client settings for requests with actions?

If a condition is specified by a client (HTTP headers If-Match or If-None-Match are present), the application has to override the data provider interface method /IWBEP/IF_MGW_APPL_SRV_RUNTIME~GET_IS_CONDI_IMPLE_FOR_ACTION.

This method provides ABAP_TRUE if the conditional handling is implemented for the specified action, otherwise ABAP_FALSE is returned. If conditions are specified by a client and the return of this method is ABAP_FALSE, a 501 response (Not implemented) is returned to the client by the framework.