Merge pull request #534 from lpabon/sdk-docs

sdk: Rework fake driver and add more docs to cloud backup

api/api.proto

@@ -992,12 +992,13 @@ service OpenStorageCredentials {
   // ##### Example
   // {% codetabs name="Golang", type="go" -%}
   // id, err := client.Create(context.Background(), &api.SdkCredentialCreateRequest{
-  //   CredentialType: &api.SdkCredentialCreateRequest_AwsCredential{
-  //     AwsCredential: &api.SdkAwsCredentialRequest{
-  //     AccessKey: "dummy-access",
-  //     SecretKey: "dummy-secret",
-  //     Endpoint:  "dummy-endpoint",
-  //     Region:    "dummy-region",
+  //     CredentialType: &api.SdkCredentialCreateRequest_AwsCredential{
+  //       AwsCredential: &api.SdkAwsCredentialRequest{
+  //       AccessKey: "dummy-access",
+  //       SecretKey: "dummy-secret",
+  //       Endpoint:  "dummy-endpoint",
+  //       Region:    "dummy-region",
+  //     },
   //   },
   // })
   // {%- language name="Python", type="py" -%}
@@ -1099,6 +1100,19 @@ service OpenStorageSchedulePolicy {
 
 // OpenStorageCloudBackup service manages backing up volumes to a cloud
 // location like Amazon, Google, or Azure.
+//
+// #### Backup
+// To create a backup, you must first call the Create() call for a specified
+// volume. To see the status of this request, use Status() which returns
+// a map where the keys are the source volume id.
+//
+// #### Restore
+// To restore, you would pass a `backup_id` of a successful backup.
+// `backup_id` can be retreived by calling Enumerate() for a specified volume.
+// Pass this `backup_id` and a new volume name to Restore() to start
+// restoring a new volume from an existing backup. To see the status of this
+// restore, pass volume id returned by Restore() to input to Status()
+//
 service OpenStorageCloudBackup {
 
   // Creates a backup request for a specified volume. Use
@@ -1153,7 +1167,7 @@ service OpenStorageCloudBackup {
   rpc Status(SdkCloudBackupStatusRequest)
     returns (SdkCloudBackupStatusResponse) {
       option(google.api.http) = {
-        get: "/v1/cloudbackups/volume/{src_volume_id}/status"
+        get: "/v1/cloudbackups/volume/{volume_id}/status"
       };
     }
 
@@ -1842,7 +1856,7 @@ message SdkCloudBackupEnumerateRequest {
 
 // SdkCloudBackupInfo has information about a backup stored by a cloud provider
 message SdkCloudBackupInfo {
-  // ID is the ID of the cloud backup
+  // This is the id as represented by the cloud provider
   string id = 1;
   // Source volumeID of the backup
   string src_volume_id = 2;
@@ -1894,7 +1908,7 @@ enum SdkCloudBackupStatusType {
 
 // SdkCloudBackupStatus defines the status of a backup stored by a cloud provider
 message SdkCloudBackupStatus {
-  // ID is the ID for the operation
+  // This is the id as represented by the cloud provider
   string backup_id = 1;
   // OpType indicates if this is a backup or restore
   SdkCloudBackupOpType optype = 2;
@@ -1910,18 +1924,22 @@ message SdkCloudBackupStatus {
   string node_id = 7;
 }
 
-// Defines a request to retreive the status of a backup for a specified volume
+// Defines a request to retreive the status of a backup or restore for a
+// specified volume
 message SdkCloudBackupStatusRequest {
-  // SrcVolumeID optional volumeID to list status of backup/restore
-  string src_volume_id = 1;
+  // This is an optional value which is used to get information on the
+  // status of a backup for the specified volume. If no volume id is provided,
+  // then status for all volumes is returned.
+  string volume_id = 1;
   // Local indicates if only those backups/restores that are
   // active on current node must be returned
   bool local = 2;
 }
 
 // Defines a response containing the status of the backups for a specified volume
 message SdkCloudBackupStatusResponse {
-  // Statuses is list of currently active/failed/done backup/restores
+  // Statuses is list of currently active/failed/done backup/restores where
+  // the key is the volume ids of current volumes being backed up or restored
   map<string, SdkCloudBackupStatus> statuses = 1;
 }
 
@@ -1953,14 +1971,14 @@ message SdkCloudBackupHistoryItem {
 // Defines a request to retreive the history of the backups for
 // a specific volume to a cloud provider
 message SdkCloudBackupHistoryRequest {
-  // This optional value defines which history of backup/restore is being
+  // This optional value defines which history of backups is being
   // requested. If not provided, it will return the history for all volumes.
   string src_volume_id = 1;
 }
 
 // Defines a response containing a list of history of backups to a cloud provider
 message SdkCloudBackupHistoryResponse {
-  // HistoryList is list of past backup/restores in the cluster
+  // HistoryList is list of past backups on this volume
   repeated SdkCloudBackupHistoryItem history_list = 1;
 }
 

api/client/sdk/js/api_grpc_pb.js

@@ -1375,12 +1375,13 @@ var OpenStorageCredentialsService = exports.OpenStorageCredentialsService = {
   // ##### Example
   // {% codetabs name="Golang", type="go" -%}
   // id, err := client.Create(context.Background(), &api.SdkCredentialCreateRequest{
-  //   CredentialType: &api.SdkCredentialCreateRequest_AwsCredential{
-  //     AwsCredential: &api.SdkAwsCredentialRequest{
-  //     AccessKey: "dummy-access",
-  //     SecretKey: "dummy-secret",
-  //     Endpoint:  "dummy-endpoint",
-  //     Region:    "dummy-region",
+  //     CredentialType: &api.SdkCredentialCreateRequest_AwsCredential{
+  //       AwsCredential: &api.SdkAwsCredentialRequest{
+  //       AccessKey: "dummy-access",
+  //       SecretKey: "dummy-secret",
+  //       Endpoint:  "dummy-endpoint",
+  //       Region:    "dummy-region",
+  //     },
   //   },
   // })
   // {%- language name="Python", type="py" -%}
@@ -1522,6 +1523,19 @@ var OpenStorageSchedulePolicyService = exports.OpenStorageSchedulePolicyService
 exports.OpenStorageSchedulePolicyClient = grpc.makeGenericClientConstructor(OpenStorageSchedulePolicyService);
 // OpenStorageCloudBackup service manages backing up volumes to a cloud
 // location like Amazon, Google, or Azure.
+//
+// #### Backup
+// To create a backup, you must first call the Create() call for a specified
+// volume. To see the status of this request, use Status() which returns
+// a map where the keys are the source volume id.
+//
+// #### Restore
+// To restore, you would pass a `backup_id` of a successful backup.
+// `backup_id` can be retreived by calling Enumerate() for a specified volume.
+// Pass this `backup_id` and a new volume name to Restore() to start
+// restoring a new volume from an existing backup. To see the status of this
+// restore, pass volume id returned by Restore() to input to Status()
+//
 var OpenStorageCloudBackupService = exports.OpenStorageCloudBackupService = {
   // Creates a backup request for a specified volume. Use
   // OpenStorageCloudBackup.Status() to get the current status of the

api/client/sdk/js/api_pb.js

@@ -24973,7 +24973,7 @@ proto.openstorage.api.SdkCloudBackupStatusRequest.prototype.toObject = function(
  */
 proto.openstorage.api.SdkCloudBackupStatusRequest.toObject = function(includeInstance, msg) {
   var f, obj = {
-    srcVolumeId: jspb.Message.getFieldWithDefault(msg, 1, ""),
+    volumeId: jspb.Message.getFieldWithDefault(msg, 1, ""),
     local: jspb.Message.getFieldWithDefault(msg, 2, false)
   };
 
@@ -25013,7 +25013,7 @@ proto.openstorage.api.SdkCloudBackupStatusRequest.deserializeBinaryFromReader =
     switch (field) {
     case 1:
       var value = /** @type {string} */ (reader.readString());
-      msg.setSrcVolumeId(value);
+      msg.setVolumeId(value);
       break;
     case 2:
       var value = /** @type {boolean} */ (reader.readBool());
@@ -25048,7 +25048,7 @@ proto.openstorage.api.SdkCloudBackupStatusRequest.prototype.serializeBinary = fu
  */
 proto.openstorage.api.SdkCloudBackupStatusRequest.serializeBinaryToWriter = function(message, writer) {
   var f = undefined;
-  f = message.getSrcVolumeId();
+  f = message.getVolumeId();
   if (f.length > 0) {
     writer.writeString(
       1,
@@ -25066,16 +25066,16 @@ proto.openstorage.api.SdkCloudBackupStatusRequest.serializeBinaryToWriter = func
 
 
 /**
- * optional string src_volume_id = 1;
+ * optional string volume_id = 1;
  * @return {string}
  */
-proto.openstorage.api.SdkCloudBackupStatusRequest.prototype.getSrcVolumeId = function() {
+proto.openstorage.api.SdkCloudBackupStatusRequest.prototype.getVolumeId = function() {
   return /** @type {string} */ (jspb.Message.getFieldWithDefault(this, 1, ""));
 };
 
 
 /** @param {string} value */
-proto.openstorage.api.SdkCloudBackupStatusRequest.prototype.setSrcVolumeId = function(value) {
+proto.openstorage.api.SdkCloudBackupStatusRequest.prototype.setVolumeId = function(value) {
   jspb.Message.setField(this, 1, value);
 };
 

api/client/sdk/python/api_pb2_grpc.py

@@ -597,6 +597,7 @@ def Create(self, request, context):
     Endpoint:  "dummy-endpoint",
     Region:    "dummy-region",
     },
+    },
     })
     {%- language name="Python", type="py" -%}
     en_resp = client.Create(api_pb2.SdkCredentialCreateRequest(
@@ -789,6 +790,19 @@ def add_OpenStorageSchedulePolicyServicer_to_server(servicer, server):
 class OpenStorageCloudBackupStub(object):
   """OpenStorageCloudBackup service manages backing up volumes to a cloud
   location like Amazon, Google, or Azure.
+
+  #### Backup
+  To create a backup, you must first call the Create() call for a specified
+  volume. To see the status of this request, use Status() which returns
+  a map where the keys are the source volume id.
+
+  #### Restore
+  To restore, you would pass a `backup_id` of a successful backup.
+  `backup_id` can be retreived by calling Enumerate() for a specified volume.
+  Pass this `backup_id` and a new volume name to Restore() to start
+  restoring a new volume from an existing backup. To see the status of this
+  restore, pass volume id returned by Restore() to input to Status()
+
   """
 
   def __init__(self, channel):
@@ -862,6 +876,19 @@ def __init__(self, channel):
 class OpenStorageCloudBackupServicer(object):
   """OpenStorageCloudBackup service manages backing up volumes to a cloud
   location like Amazon, Google, or Azure.
+
+  #### Backup
+  To create a backup, you must first call the Create() call for a specified
+  volume. To see the status of this request, use Status() which returns
+  a map where the keys are the source volume id.
+
+  #### Restore
+  To restore, you would pass a `backup_id` of a successful backup.
+  `backup_id` can be retreived by calling Enumerate() for a specified volume.
+  Pass this `backup_id` and a new volume name to Restore() to start
+  restoring a new volume from an existing backup. To see the status of this
+  restore, pass volume id returned by Restore() to input to Status()
+
   """
 
   def Create(self, request, context):

api/server/sdk/api/api.swagger.json

@@ -333,7 +333,7 @@
         ]
       }
     },
-    "/v1/cloudbackups/volume/{src_volume_id}/status": {
+    "/v1/cloudbackups/volume/{volume_id}/status": {
       "get": {
         "summary": "Status returns the status of any cloud backups of a volume",
         "operationId": "Status",
@@ -347,7 +347,7 @@
         },
         "parameters": [
           {
-            "name": "src_volume_id",
+            "name": "volume_id",
             "in": "path",
             "required": true,
             "type": "string"
@@ -519,7 +519,7 @@
       },
       "post": {
         "summary": "Create is used to submit cloud credentials. It will return an\nid of the credentials once they are verified to work.",
-        "description": "##### Example\n{% codetabs name=\"Golang\", type=\"go\" -%}\nid, err := client.Create(context.Background(), \u0026api.SdkCredentialCreateRequest{\n  CredentialType: \u0026api.SdkCredentialCreateRequest_AwsCredential{\n    AwsCredential: \u0026api.SdkAwsCredentialRequest{\n    AccessKey: \"dummy-access\",\n    SecretKey: \"dummy-secret\",\n    Endpoint:  \"dummy-endpoint\",\n    Region:    \"dummy-region\",\n  },\n})\n{%- language name=\"Python\", type=\"py\" -%}\nen_resp = client.Create(api_pb2.SdkCredentialCreateRequest(\n  aws_credential=api_pb2.SdkAwsCredentialRequest(\n    access_key='dummy-access',\n    secret_key='dumm-secret',\n    endpoint='dummy-endpoint',\n    region='dummy-region')))\n{%- endcodetabs %}",
+        "description": "##### Example\n{% codetabs name=\"Golang\", type=\"go\" -%}\nid, err := client.Create(context.Background(), \u0026api.SdkCredentialCreateRequest{\n    CredentialType: \u0026api.SdkCredentialCreateRequest_AwsCredential{\n      AwsCredential: \u0026api.SdkAwsCredentialRequest{\n      AccessKey: \"dummy-access\",\n      SecretKey: \"dummy-secret\",\n      Endpoint:  \"dummy-endpoint\",\n      Region:    \"dummy-region\",\n    },\n  },\n})\n{%- language name=\"Python\", type=\"py\" -%}\nen_resp = client.Create(api_pb2.SdkCredentialCreateRequest(\n  aws_credential=api_pb2.SdkAwsCredentialRequest(\n    access_key='dummy-access',\n    secret_key='dumm-secret',\n    endpoint='dummy-endpoint',\n    region='dummy-region')))\n{%- endcodetabs %}",
         "operationId": "Create",
         "responses": {
           "200": {
@@ -1613,7 +1613,7 @@
           "items": {
             "$ref": "#/definitions/apiSdkCloudBackupHistoryItem"
           },
-          "title": "HistoryList is list of past backup/restores in the cluster"
+          "title": "HistoryList is list of past backups on this volume"
         }
       },
       "title": "Defines a response containing a list of history of backups to a cloud provider"
@@ -1623,7 +1623,7 @@
       "properties": {
         "id": {
           "type": "string",
-          "title": "ID is the ID of the cloud backup"
+          "title": "This is the id as represented by the cloud provider"
         },
         "src_volume_id": {
           "type": "string",
@@ -1790,7 +1790,7 @@
       "properties": {
         "backup_id": {
           "type": "string",
-          "title": "ID is the ID for the operation"
+          "title": "This is the id as represented by the cloud provider"
         },
         "optype": {
           "$ref": "#/definitions/apiSdkCloudBackupOpType",
@@ -1830,7 +1830,7 @@
           "additionalProperties": {
             "$ref": "#/definitions/apiSdkCloudBackupStatus"
           },
-          "title": "Statuses is list of currently active/failed/done backup/restores"
+          "title": "Statuses is list of currently active/failed/done backup/restores where\nthe key is the volume ids of current volumes being backed up or restored"
         }
       },
       "title": "Defines a response containing the status of the backups for a specified volume"