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.