Database transactions

It is possible for a REST API caller to supply a unique transaction ID while making a request. This ID ultimately maps to an insert operation into the TransactionID table in the database. If this transaction ID does not already exist, the REST request completes successfully. However, if a transaction with that ID already exists in the TransactionID table, the database commit for the API fails.

You can use this functionality to avoid making duplicates requests, in cases in which the request actually issues a database commit. This functionality works globally for any API handler that commits a bundle to the database.

Transaction ID usage

To use this functionality, the caller needs to specify the transaction ID in the GW-DBTransaction-ID custom header. The value of the header can be any alphanumeric string generated by the client, up to 128 characters. The header must be a globally unique request ID.

Transaction ID limitations

The transaction ID functionality has the following limitations:
  • It only works with APIs whose handlers actually commit to the database.
  • It only works if the API commits to the database a single time only (except for certain very rare exceptions)
  • It only works if the database commit is one of the following:
    • The database commit is the only interesting side effect of the API call.
    • The database commit happens before any other side effect happens (such as notifications to external systems).
  • It does not work for duplicate requests. Duplicate requests do not return identical responses back to the client. Instead, PolicyCenter marks the request as failed. The client code needs to decide how (or even if) to handle that situation

Reserving a database connection

To reserve a database connection for the duration of the request handling by the REST framework, set the following Swagger operation to true:
  • x-gw-reserve-db-connection