Update api/docs for non-conditional writes

build.rs

@@ -14,7 +14,7 @@ fn main() {
 #[cfg(feature = "genproto")]
 fn generate_protos() {
 	download_file(
-				"https://raw.githubusercontent.com/lightningdevkit/vss-server/ac646dd419bc70db2b79772b1bfa1b2d9a4b8b53/app/src/main/proto/vss.proto",
+				"https://raw.githubusercontent.com/lightningdevkit/vss-server/e1a88afd61f56d7e8e90a32036ca12389e36fe44/app/src/main/proto/vss.proto",
 				"src/proto/vss.proto",
 		).unwrap();
 

src/types.rs

@@ -71,18 +71,26 @@ pub struct PutObjectRequest {
 	/// a database-transaction in an all-or-nothing fashion.
 	/// All Items in a single `PutObjectRequest` must have distinct keys.
 	///
-	/// Clients are expected to store a `version` against every `key`.
-	/// The write will succeed if the current DB version against the `key` is the same as in the request.
-	/// When initiating a `PutObjectRequest`, the request should contain their client-side version for
-	/// that key-value.
-	///
-	/// For the first write of any key, the `version` should be '0'. If the write succeeds, the client
-	/// must increment their corresponding key versions (client-side) by 1.
-	/// The server increments key versions (server-side) for every successful write, hence this
-	/// client-side increment is required to ensure matching versions. These updated key versions should
-	/// be used in subsequent `PutObjectRequest`s for the keys.
+	/// Key-level versioning (Conditional Write):
+	///    Clients are expected to store a `version` against every `key`.
+	///    The write will succeed if the current DB version against the `key` is the same as in the request.
+	///    When initiating a `PutObjectRequest`, the request should contain their client-side `version`
+	///    for that key-value.
 	///
-	/// Requests with a conflicting version will fail with `CONFLICT_EXCEPTION` as ErrorCode.
+	///    For the first write of any `key`, the `version` should be '0'. If the write succeeds, the client
+	///    must increment their corresponding key versions (client-side) by 1.
+	///    The server increments key versions (server-side) for every successful write, hence this
+	///    client-side increment is required to ensure matching versions. These updated key versions should
+	///    be used in subsequent `PutObjectRequest`s for the keys.
+	///
+	///    Requests with a conflicting/mismatched version will fail with `CONFLICT_EXCEPTION` as ErrorCode
+	///    for conditional writes.
+	///
+	/// Skipping key-level versioning (Non-conditional Write):
+	///    If you wish to skip key-level version checks, set the `version` against the `key` to '-1'.
+	///    This will perform a non-conditional write query, after which the `version` against the `key`
+	///    is reset to '1'. Hence, the next `PutObjectRequest` for the `key` can be either
+	///    a non-conditional write or a conditional write with `version` set to `1`.
 	///
 	/// Considerations for transactions:
 	/// Transaction writes of multiple items have a performance overhead, hence it is recommended to use
@@ -99,13 +107,20 @@ pub struct PutObjectRequest {
 	/// Items to be deleted as a result of this `PutObjectRequest`.
 	///
 	/// Each item in the `delete_items` field consists of a `key` and its corresponding `version`.
-	/// The `version` is used to perform a version check before deleting the item.
-	/// The delete will only succeed if the current database version against the `key` is the same as the `version`
-	/// specified in the request.
+	///
+	/// Key-Level Versioning (Conditional Delete):
+	///    The `version` is used to perform a version check before deleting the item.
+	///    The delete will only succeed if the current database version against the `key` is the same as
+	///    the `version` specified in the request.
+	///
+	/// Skipping key-level versioning (Non-conditional Delete):
+	///    If you wish to skip key-level version checks, set the `version` against the `key` to '-1'.
+	///    This will perform a non-conditional delete query.
 	///
 	/// Fails with `CONFLICT_EXCEPTION` as the ErrorCode if:
 	///    * The requested item does not exist.
-	///    * The requested item does exist but there is a version-number mismatch with the one in the database.
+	///    * The requested item does exist but there is a version-number mismatch (in conditional delete)
+	///      with the one in the database.
 	///
 	/// Multiple items in the `delete_items` field, along with the `transaction_items`, are written in a
 	/// database transaction in an all-or-nothing fashion.
@@ -133,8 +148,15 @@ pub struct DeleteObjectRequest {
 	/// Item to be deleted as a result of this `DeleteObjectRequest`.
 	///
 	/// An item consists of a `key` and its corresponding `version`.
-	/// The item is only deleted if the current database version against the `key` is the same as the `version`
-	/// specified in the request.
+	///
+	/// Key-level Versioning (Conditional Delete):
+	///    The item is only deleted if the current database version against the `key` is the same as
+	///    the `version` specified in the request.
+	///
+	/// Skipping key-level versioning (Non-conditional Delete):
+	///    If you wish to skip key-level version checks, set the `version` against the `key` to '-1'.
+	///    This will perform a non-conditional delete query.
+	///
 	/// This operation is idempotent, that is, multiple delete calls for the same item will not fail.
 	///
 	/// If the requested item does not exist, this operation will not fail.