Preventing duplicate database transactions

In some circumstances, when a caller application is making a request that involves a commit to the database, the application may want to ensure that the request is processed only once. The caller application can do this using the GW-DBTransaction-ID header.

The GW-DBTransaction-ID header identifies a transaction ID (a string of up to 128 characters). When submitted with a system API call, the system API attempts to insert the value into the database's TransactionID table.

  • If the value does not already exist in the table, the insert is successful. The system API assumes the transaction has not already been committed, and the call is processed as normal.
  • If the value does exist in the table, the insert fails. The system API assumes the transaction has already been committed, and the call is rejected. The system API returns a 400 status code with an gw.api.webservice.exception.AlreadyExecutedException error.

For the call to success, the transaction ID specified in the header must be globally unique across all clients, APIs and web services.

The GW-DBTransaction-ID header has the following limitations:

  • It only works with system APIs that commit data to the database.
  • It only works when the system API commits a single time only. (System APIs that commit multiple times are rare.)
  • It only works if the commit is either the only side effect of the call, or if the commit happens before any other side effects, such as the sending of notifications to external systems.

Duplicate requests do not return identical responses. The first request will succeed, but subsequent requests will fail. It is the responsibility of the caller application to decide how or if to handle this situation.