Add versioning info and rename APIs

Author: G8XSU

src/main/proto/ess.proto

@@ -3,39 +3,57 @@ option java_multiple_files = true;
 package org.ess;
 
 service EncryptedStorageService {
-  rpc get(GetRequest) returns (GetResponse);
-  rpc put(PutRequest) returns (PutResponse);
-  //TODO: Add getKeysSummary (Gives version numbers for all keys in a store) and list by prefix API's
+  rpc get(GetObjectRequest) returns (GetObjectResponse);
+  rpc put(PutObjectRequest) returns (PutObjectResponse);
+  //TODO: Add getKeysSummary (Gives version numbers for all keys in a store) and list by prefix APIs
 }
 
-message GetRequest {
+message GetObjectRequest {
   /*
-    All API's operate within a single storeId.
+    All APIs operate within a single storeId.
     StoreId is keyspace identifier. Ref: https://en.wikipedia.org/wiki/Keyspace_(distributed_data_store)
     It is up to clients to use single or multiple store's for their usage.
    */
   string storeId = 1;
   string key = 2;
 }
-message GetResponse {
+message GetObjectResponse {
   bool success = 1;
   KeyValue value = 2;
 
-  // Only present when success = false
+  // Optional, only present when success = false
   optional ErrorResponse errorResponse = 3;
 }
 
-message PutRequest {
+message PutObjectRequest {
   string storeId = 1;
   /*
-  If present, write will only succeed if current DB globalVersion against a storeId is
-  same as in request.
+    If present, write will only succeed if current DB globalVersion against a storeId is
+    same as in request.
+    Client is expected to send their current global version at hand.
+
+    For first write of store, version should be '0'. If write succeeds, clients must increment
+    their global version(on device) by 1.
+
+    Requests with conflicting version will fail with [`ConflictException`] as ErrorCode.
    */
   optional int64 globalVersion = 2;
+
+  /*
+    Each key is supplied with its corresponding version.
+
+    Write will only succeed if current DB version against key is same as in request.
+    Clients are expected to send their current version at hand in the request.
+
+    For first write of key, version should be '0'. If write succeeds, clients must increment
+    their corresponding key versions(on device) by 1.
+
+    Requests with conflicting version will fail with [`ConflictException`] as ErrorCode.
+   */
   repeated KeyValue transactionItems = 3;
 }
 
-message PutResponse {
+message PutObjectResponse {
   bool success = 1;
   optional ErrorResponse errorResponse = 2;
 }
@@ -54,7 +72,6 @@ enum ErrorCode{
 message KeyValue {
   string key = 1;
 
-  // Write will only succeed if current DB version against key is same as in request.
   int64 version = 2;
 
   bytes value = 3;