api-ref: Add backup import and export

During the migration to in-tree api-ref docs we somehow lost the details
for backup export_record and import_record. Adding back in.

Also fixing up a few records that referred to the wrong parameter record
names, resulting in their descriptions referring to volume transfer for
backup operations.

Change-Id: I6fc555729c1b8404887d41424831fc48934f1491
Closes-bug: #1628812
Closes-bug: #1712923

api-ref/source/v2/ext-backups.inc

@@ -70,17 +70,17 @@ Response Parameters
    - object_count: object_count
    - fail_reason: fail_reason
    - description: description
-   - links: links
+   - links: links_1
    - availability_zone: availability_zone
    - created_at: created_at
    - updated_at: updated_at
-   - name: name
+   - name: name_1
    - has_dependent_backups: has_dependent_backups
    - volume_id: volume_id
    - container: container
    - backups: backups
    - size: size
-   - id: id
+   - id: id_1
    - is_incremental: is_incremental
    - data_timestamp: data_timestamp
    - snapshot_id: snapshot_id_2
@@ -122,17 +122,17 @@ Response Parameters
    - object_count: object_count
    - container: container
    - description: description
-   - links: links
+   - links: links_1
    - availability_zone: availability_zone
    - created_at: created_at
    - updated_at: updated_at
-   - name: name
+   - name: name_1
    - has_dependent_backups: has_dependent_backups
    - volume_id: volume_id
    - fail_reason: fail_reason
    - size: size
    - backup: backup
-   - id: id
+   - id: id_1
    - is_incremental: is_incremental
    - data_timestamp: data_timestamp
    - snapshot_id: snapshot_id_2
@@ -186,7 +186,7 @@ Request
 .. rest_parameters:: parameters.yaml
 
    - restore: restore
-   - name: name
+   - name: name_1
    - volume_id: volume_id
    - tenant_id: tenant_id
    - backup_id: backup_id
@@ -234,7 +234,7 @@ Request
    - volume_id: volume_id
    - force: force
    - backup: backup
-   - name: name
+   - name: name_1
    - tenant_id: tenant_id
    - snapshot_id: snapshot_id_2
 
@@ -250,9 +250,9 @@ Response Parameters
 .. rest_parameters:: parameters.yaml
 
    - backup: backup
-   - id: id
+   - id: id_1
-   - links: links
+   - links: links_1
-   - name: name
+   - name: name_1
 
 List backups
 ~~~~~~~~~~~~
@@ -281,12 +281,92 @@ Response Parameters
 .. rest_parameters:: parameters.yaml
 
    - backups: backups
-   - id: id
+   - id: id_1
-   - links: links
+   - links: links_1
-   - name: name
+   - name: name_1
 
 Response Example
 ----------------
 
 .. literalinclude:: ./samples/backups-list-response.json
    :language: javascript
+
+
+Export backup
+~~~~~~~~~~~~~
+
+.. rest_method::  GET /v2/{project_id}/backups/{backup_id}/export_record
+
+Export information about a backup.
+
+
+Normal response codes: 200
+Error response codes: badRequest(400), itemNotFound(404)
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - project_id: project_id_path
+   - backup_id: backup_id
+
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - backup_service: backup_service
+   - backup_url: backup_url
+
+Response Example
+----------------
+
+.. literalinclude:: ./samples/backup-record-export-response.json
+   :language: javascript
+
+
+Import backup
+~~~~~~~~~~~~~
+
+.. rest_method::  POST /v2/{project_id}/backups/{backup_id}/import_record
+
+Import information about a backup.
+
+
+Normal response codes: 201
+Error response codes: badRequest(400), serviceUnavailable(503)
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - project_id: project_id_path
+   - backup_id: backup_id
+
+
+Request Example
+---------------
+
+.. literalinclude:: ./samples/backup-record-import-request.json
+   :language: javascript
+
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - id: id_1
+   - links: links_1
+   - name: name_1
+
+Response Example
+----------------
+
+.. literalinclude:: ./samples/backup-record-import-response.json
+

api-ref/source/v2/parameters.yaml

@@ -361,6 +361,18 @@ backup:
   in: body
   required: true
   type: object
+backup_service:
+  description: |
+    The service used to perform the backup.
+  in: body
+  required: true
+  type: string
+backup_url:
+  description: |
+    The backup encoded metadata.
+  in: body
+  required: true
+  type: string
 backups:
   description: |
     A list of ``backup`` objects.

api-ref/source/v3/ext-backups.inc

@@ -73,17 +73,17 @@ Response Parameters
    - object_count: object_count
    - fail_reason: fail_reason
    - description: description
-   - links: links
+   - links: links_1
    - availability_zone: availability_zone
    - created_at: created_at
    - updated_at: updated_at
-   - name: name
+   - name: name_1
    - has_dependent_backups: has_dependent_backups
    - volume_id: volume_id
    - container: container
    - backups: backups
    - size: size
-   - id: id
+   - id: id_1
    - is_incremental: is_incremental
    - data_timestamp: data_timestamp
    - snapshot_id: snapshot_id_2
@@ -126,17 +126,17 @@ Response Parameters
    - object_count: object_count
    - container: container
    - description: description
-   - links: links
+   - links: links_1
    - availability_zone: availability_zone
    - created_at: created_at
    - updated_at: updated_at
-   - name: name
+   - name: name_1
    - has_dependent_backups: has_dependent_backups
    - volume_id: volume_id
    - fail_reason: fail_reason
    - size: size
    - backup: backup
-   - id: id
+   - id: id_1
    - is_incremental: is_incremental
    - data_timestamp: data_timestamp
    - snapshot_id: snapshot_id_2
@@ -188,7 +188,7 @@ Request
 .. rest_parameters:: parameters.yaml
 
    - restore: restore
-   - name: name
+   - name: name_1
    - volume_id: volume_id
    - project_id: project_id_path
    - backup_id: backup_id
@@ -252,9 +252,9 @@ Response Parameters
 .. rest_parameters:: parameters.yaml
 
    - backup: backup
-   - id: id
+   - id: id_1
-   - links: links
+   - links: links_1
-   - name: name
+   - name: name_1
 
 
 Update a backup
@@ -291,9 +291,9 @@ Response Parameters
 .. rest_parameters:: parameters.yaml
 
    - backup: backup
-   - id: id
+   - id: id_1
-   - links: links
+   - links: links_1
-   - name: name
+   - name: name_1
 
 Response Example
 ----------------
@@ -331,12 +331,92 @@ Response Parameters
 .. rest_parameters:: parameters.yaml
 
    - backups: backups
-   - id: id
+   - id: id_1
-   - links: links
+   - links: links_1
-   - name: name
+   - name: name_1
 
 Response Example
 ----------------
 
 .. literalinclude:: ./samples/backups-list-response.json
    :language: javascript
+
+
+Export a backup
+~~~~~~~~~~~~~~~
+
+.. rest_method::  GET /v3/{project_id}/backups/{backup_id}/export_record
+
+Export information about a backup.
+
+
+Normal response codes: 200
+Error response codes: badRequest(400), itemNotFound(404)
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - project_id: project_id_path
+   - backup_id: backup_id
+
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - backup_service: backup_service
+   - backup_url: backup_url
+
+Response Example
+----------------
+
+.. literalinclude:: ./samples/backup-record-export-response.json
+   :language: javascript
+
+
+Import a backup
+~~~~~~~~~~~~~~~
+
+.. rest_method::  POST /v3/{project_id}/backups/{backup_id}/import_record
+
+Import information about a backup.
+
+
+Normal response codes: 201
+Error response codes: badRequest(400), serviceUnavailable(503)
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - project_id: project_id_path
+   - backup_id: backup_id
+
+
+Request Example
+---------------
+
+.. literalinclude:: ./samples/backup-record-import-request.json
+   :language: javascript
+
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - id: id_1
+   - links: links_1
+   - name: name_1
+
+Response Example
+----------------
+
+.. literalinclude:: ./samples/backup-record-import-response.json
+

api-ref/source/v3/parameters.yaml

@@ -502,6 +502,18 @@ backup_gigabytes_usage:
   in: body
   required: true
   type: object
+backup_service:
+  description: |
+    The service used to perform the backup.
+  in: body
+  required: true
+  type: string
+backup_url:
+  description: |
+    The backup encoded metadata.
+  in: body
+  required: true
+  type: string
 backups:
   description: |
     A list of ``backup`` objects.