Merge ~jsseidel/maas:jsseidel-blockdevices-api-annotations into maas:master

[Spencer Seidel]

Added API annotations and examples to blockdevices.

b7435ba... by Spencer Seidel on 2018-12-03

Merge branch 'master' into jsseidel-blockdevices-api-annotations

[Newell Jensen (newell-jensen)]

Looks good.

review: Approve

diff --git a/src/maasserver/api/blockdevices.py b/src/maasserver/api/blockdevices.py
index 3854b31..2815e9f 100644
--- a/src/maasserver/api/blockdevices.py
+++ b/src/maasserver/api/blockdevices.py
@@ -82,9 +82,21 @@ class BlockDevicesHandler(OperationsHandler):
         return ('blockdevices_handler', ["system_id"])
 
     def read(self, request, system_id):
-        """List all block devices belonging to a machine.
+        """@description-title List block devices
+        @description List all block devices belonging to a machine.
 
-        Returns 404 if the machine is not found.
+        @param (string) "{system_id}" [required=true] The machine system_id.
+
+        @success (http-status-code) "server-success" 200
+        @success (json) "success-json" A JSON object containing a list of block
+        devices.
+        @success-example "success-json" [exkey=block-devs-read] placeholder
+        text
+
+        @error (http-status-code) "404" 404
+        @error (content) "not-found" The requested machine is not found.
+        @error-example "not-found"
+            Not Found
         """
         machine = Machine.objects.get_node_or_404(
             system_id, request.user, NodePermission.view)
@@ -92,18 +104,37 @@ class BlockDevicesHandler(OperationsHandler):
 
     @admin_method
     def create(self, request, system_id):
-        """Create a physical block device.
-
-        :param name: Name of the block device.
-        :param model: Model of the block device.
-        :param serial: Serial number of the block device.
-        :param id_path: (optional) Only used if model and serial cannot be
-            provided. This should be a path that is fixed and doesn't change
-            depending on the boot order or kernel version.
-        :param size: Size of the block device.
-        :param block_size: Block size of the block device.
-
-        Returns 404 if the node is not found.
+        """@description-title Create a block device
+        @description Create a physical block device.
+
+        @param (string) "{system_id}" [required=true] The machine system_id.
+
+        @param (string) "name" [required=true] Name of the block device.
+
+        @param (string) "model" [required=false] Model of the block device.
+
+        @param (string) "serial" [required=false] Serial number of the block
+        device.
+
+        @param (string) "id_path" [required=false] Only used if model and
+        serial cannot be provided. This should be a path that is fixed and
+        doesn't change depending on the boot order or kernel version.
+
+        @param (string) "size" [required=true] Size of the block device.
+
+        @param (string) "block_size" [required=true] Block size of the block
+        device.
+
+        @success (http-status-code) "server-success" 200
+        @success (json) "success-json" A JSON object containing the new block
+        device.
+        @success-example "success-json" [exkey=block-devs-create] placeholder
+        text
+
+        @error (http-status-code) "404" 404
+        @error (content) "not-found" The requested machine is not found.
+        @error-example "not-found"
+            Not Found
         """
         machine = Machine.objects.get_node_or_404(
             system_id, request.user, NodePermission.admin)
@@ -212,19 +243,48 @@ class BlockDeviceHandler(OperationsHandler):
         return None
 
     def read(self, request, system_id, id):
-        """Read block device on node.
-
-        Returns 404 if the machine or block device is not found.
+        """@description-title Read a block device
+        @description Read a block device on a given machine.
+
+        @param (string) "{system_id}" [required=true] The machine system_id.
+        @param (string) "{id}" [required=true] The block device's id.
+
+        @success (http-status-code) "server-success" 200
+        @success (json) "success-json" A JSON object containing the requested
+        block device.
+        @success-example "success-json" [exkey=block-devs-read-by-id]
+        placeholder text
+
+        @error (http-status-code) "404" 404
+        @error (content) "not-found" The requested machine or block device is
+        not found.
+        @error-example "not-found"
+            Not Found
         """
         return BlockDevice.objects.get_block_device_or_404(
             system_id, id, request.user, NodePermission.view)
 
     def delete(self, request, system_id, id):
-        """Delete block device on a machine.
+        """@description-title Delete a block device
+        @description Delete block device on a given machine.
 
-        Returns 404 if the machine or block device is not found.
-        Returns 403 if the user is not allowed to delete the block device.
-        Returns 409 if the machine is not Ready.
+        @param (string) "{system_id}" [required=true] The machine system_id.
+        @param (string) "{id}" [required=true] The block device's id.
+
+        @success (http-status-code) "204" 204
+
+        @error (http-status-code) "403" 403
+        @error (content) "no-perms" The user does not have permissions to
+        delete the block device.
+
+        @error (http-status-code) "404" 404
+        @error (content) "not-found" The requested machine or block device is
+        not found.
+        @error-example "not-found"
+            Not Found
+
+        @error (http-status-code) "409" 409
+        @error (content) "not-ready" The requested machine is not ready.
         """
         device = BlockDevice.objects.get_block_device_or_404(
             system_id, id, request.user, NodePermission.admin)
@@ -236,34 +296,63 @@ class BlockDeviceHandler(OperationsHandler):
         return rc.DELETED
 
     def update(self, request, system_id, id):
-        """Update block device on a machine.
+        """@description-title Update a block device
+        @description Update block device on a given machine.
 
         Machines must have a status of Ready to have access to all options.
         Machines with Deployed status can only have the name, model, serial,
         and/or id_path updated for a block device. This is intented to allow a
         bad block device to be replaced while the machine remains deployed.
 
-        Fields for physical block device:
+        @param (string) "{system_id}" [required=true] The machine system_id.
+        @param (string) "{id}" [required=true] The block device's id.
+
+        @param (string) "name" [required=false] (Physical devices) Name of the
+        block device.
+
+        @param (string) "model" [required=false] (Physical devices) Model of
+        the block device.
+
+        @param (string) "serial" [required=false] (Physical devices) Serial
+        number of the block device.
+
+        @param (string) "id_path" [required=false] (Physical devices) Only used
+        if model and serial cannot be provided. This should be a path that is
+        fixed and doesn't change depending on the boot order or kernel version.
+
+        @param (string) "size" [required=false] (Physical devices) Size of the
+        block device.
+
+        @param (string) "block_size" [required=false] (Physical devices) Block
+        size of the block device.
+
+        @param (string) "name" [required=false] (Virtual devices) Name of
+        the block device.
+
+        @param (string) "uuid" [required=false] (Virtual devices) UUID of
+        the block device.
 
-        :param name: Name of the block device.
-        :param model: Model of the block device.
-        :param serial: Serial number of the block device.
-        :param id_path: (optional) Only used if model and serial cannot be \
-            provided. This should be a path that is fixed and doesn't change \
-            depending on the boot order or kernel version.
-        :param size: Size of the block device.
-        :param block_size: Block size of the block device.
+        @param (string) "size" [required=false] (Virtual devices) Size of
+        the block device. (Only allowed for logical volumes.)
 
-        Fields for virtual block device:
+        @success (http-status-code) "server-success" 200
+        @success (json) "success-json" A JSON object containing the updated
+        block device.
+        @success-example "success-json" [exkey=block-devs-update] placeholder
+        text
 
-        :param name: Name of the block device.
-        :param uuid: UUID of the block device.
-        :param size: Size of the block device. (Only allowed for logical \
-            volumes.)
+        @error (http-status-code) "403" 403
+        @error (content) "no-perms" The user does not have permissions to
+        update the block device.
 
-        Returns 404 if the machine or block device is not found.
-        Returns 403 if the user is not allowed to update the block device.
-        Returns 409 if the machine is not Ready.
+        @error (http-status-code) "404" 404
+        @error (content) "not-found" The requested machine or block device is
+        not found.
+        @error-example "not-found"
+            Not Found
+
+        @error (http-status-code) "409" 409
+        @error (content) "not-ready" The requested machine is not ready.
         """
         device = BlockDevice.objects.get_block_device_or_404(
             system_id, id, request.user, NodePermission.admin)
@@ -296,13 +385,32 @@ class BlockDeviceHandler(OperationsHandler):
 
     @operation(idempotent=False)
     def add_tag(self, request, system_id, id):
-        """Add a tag to block device on a machine.
+        """@description-title Add a tag
+        @description Add a tag to block device on a given machine.
+
+        @param (string) "{system_id}" [required=true] The machine system_id.
+        @param (string) "{id}" [required=true] The block device's id.
+
+        @param (string) "tag" [required=true] The tag being added.
 
-        :param tag: The tag being added.
+        @success (http-status-code) "server-success" 200
+        @success (json) "success-json" A JSON object containing the updated
+        block device.
+        @success-example "success-json" [exkey=block-devs-add-tag] placeholder
+        text
 
-        Returns 404 if the machine or block device is not found.
-        Returns 403 if the user is not allowed to update the block device.
-        Returns 409 if the machine is not Ready.
+        @error (http-status-code) "403" 403
+        @error (content) "no-perms" The user does not have permissions to
+        add a tag.
+
+        @error (http-status-code) "404" 404
+        @error (content) "not-found" The requested machine or block device is
+        not found.
+        @error-example "not-found"
+            Not Found
+
+        @error (http-status-code) "409" 409
+        @error (content) "not-ready" The requested machine is not ready.
         """
         device = BlockDevice.objects.get_block_device_or_404(
             system_id, id, request.user, NodePermission.admin)
@@ -316,13 +424,32 @@ class BlockDeviceHandler(OperationsHandler):
 
     @operation(idempotent=False)
     def remove_tag(self, request, system_id, id):
-        """Remove a tag from block device on a machine.
+        """@description-title Remove a tag
+        @description Remove a tag from block device on a given machine.
+
+        @param (string) "{system_id}" [required=true] The machine system_id.
+        @param (string) "{id}" [required=true] The block device's id.
 
-        :param tag: The tag being removed.
+        @param (string) "tag" [required=false] The tag being removed.
 
-        Returns 404 if the machine or block device is not found.
-        Returns 403 if the user is not allowed to update the block device.
-        Returns 409 if the machine is not Ready.
+        @success (http-status-code) "server-success" 200
+        @success (json) "success-json" A JSON object containing the updated
+        block device.
+        @success-example "success-json" [exkey=block-devs-remove-tag]
+        placeholder text
+
+        @error (http-status-code) "403" 403
+        @error (content) "no-perms" The user does not have permissions to
+        remove a tag.
+
+        @error (http-status-code) "404" 404
+        @error (content) "not-found" The requested machine or block device is
+        not found.
+        @error-example "not-found"
+            Not Found
+
+        @error (http-status-code) "409" 409
+        @error (content) "not-ready" The requested machine is not ready.
         """
         device = BlockDevice.objects.get_block_device_or_404(
             system_id, id, request.user, NodePermission.admin)
@@ -336,15 +463,34 @@ class BlockDeviceHandler(OperationsHandler):
 
     @operation(idempotent=False)
     def format(self, request, system_id, id):
-        """Format block device with filesystem.
+        """@description-title Format block device
+        @description Format block device with filesystem.
+
+        @param (string) "{system_id}" [required=true] The machine system_id.
+        @param (string) "{id}" [required=true] The block device's id.
+
+        @param (string) "fstype" [required=true] Type of filesystem.
+
+        @param (string) "uuid" [required=false] UUID of the filesystem.
 
-        :param fstype: Type of filesystem.
-        :param uuid: UUID of the filesystem.
+        @success (http-status-code) "server-success" 200
+        @success (json) "success-json" A JSON object containing the updated
+        block device.
+        @success-example "success-json" [exkey=block-devs-format] placeholder
+        text
 
-        Returns 403 when the user doesn't have the ability to format the \
-            block device.
-        Returns 404 if the machine or block device is not found.
-        Returns 409 if the machine is not Ready or Allocated.
+        @error (http-status-code) "403" 403
+        @error (content) "no-perms" The user does not have permissions to
+        format the block device.
+
+        @error (http-status-code) "404" 404
+        @error (content) "not-found" The requested machine or block device is
+        not found.
+        @error-example "not-found"
+            Not Found
+
+        @error (http-status-code) "409" 409
+        @error (content) "not-ready" The requested machine is not ready.
         """
         device = BlockDevice.objects.get_block_device_or_404(
             system_id, id, request.user, NodePermission.edit)
@@ -359,14 +505,34 @@ class BlockDeviceHandler(OperationsHandler):
 
     @operation(idempotent=False)
     def unformat(self, request, system_id, id):
-        """Unformat block device with filesystem.
-
-        Returns 400 if the block device is not formatted, currently mounted, \
-            or part of a filesystem group.
-        Returns 403 when the user doesn't have the ability to unformat the \
-            block device.
-        Returns 404 if the machine or block device is not found.
-        Returns 409 if the machine is not Ready or Allocated.
+        """@description-title Unformat a block device
+        @description Unformat a previously formatted block device.
+
+        @param (string) "{system_id}" [required=true] The machine system_id.
+        @param (string) "{id}" [required=true] The block device's id.
+
+        @success (http-status-code) "server-success" 200
+        @success (json) "success-json" A JSON object containing
+        the updated block device.
+        @success-example "success-json" [exkey=block-devs-unformat] placeholder
+        text
+
+        @error (http-status-code) "400" 400
+        @error (content) "problem" The block device is not formatted, currently
+        mounted, or part of a filesystem group.
+
+        @error (http-status-code) "403" 403
+        @error (content) "no-perms" The user does not have permissions to
+        unformat the block device.
+
+        @error (http-status-code) "404" 404
+        @error (content) "not-found" The requested machine or block device is
+        not found.
+        @error-example "not-found"
+            Not Found
+
+        @error (http-status-code) "409" 409
+        @error (content) "not-ready" The requested machine is not ready.
         """
         device = BlockDevice.objects.get_block_device_or_404(
             system_id, id, request.user, NodePermission.edit)
@@ -392,15 +558,36 @@ class BlockDeviceHandler(OperationsHandler):
 
     @operation(idempotent=False)
     def mount(self, request, system_id, id):
-        """Mount the filesystem on block device.
+        """@description-title Mount a filesystem
+        @description Mount the filesystem on block device.
+
+        @param (string) "{system_id}" [required=true] The machine system_id.
+        @param (string) "{id}" [required=true] The block device's id.
+
+        @param (string) "mount_point" [required=true] Path on the filesystem
+        to mount.
+
+        @param (string) "mount_options" [required=false] Options to pass to
+        mount(8).
+
+        @success (http-status-code) "server-success" 200
+        @success (json) "success-json" A JSON object containing the updated
+        block device.
+        @success-example "success-json" [exkey=block-devs-mount] placeholder
+        text
 
-        :param mount_point: Path on the filesystem to mount.
-        :param mount_options: Options to pass to mount(8).
+        @error (http-status-code) "403" 403
+        @error (content) "no-perms" The user does not have permissions to
+        mount the filesystem.
 
-        Returns 403 when the user doesn't have the ability to mount the \
-            block device.
-        Returns 404 if the machine or block device is not found.
-        Returns 409 if the machine is not Ready or Allocated.
+        @error (http-status-code) "404" 404
+        @error (content) "not-found" The requested machine or block device is
+        not found.
+        @error-example "not-found"
+            Not Found
+
+        @error (http-status-code) "409" 409
+        @error (content) "not-ready" The requested machine is not ready.
         """
         device = BlockDevice.objects.get_block_device_or_404(
             system_id, id, request.user, NodePermission.edit)
@@ -416,14 +603,34 @@ class BlockDeviceHandler(OperationsHandler):
 
     @operation(idempotent=False)
     def unmount(self, request, system_id, id):
-        """Unmount the filesystem on block device.
-
-        Returns 400 if the block device is not formatted or not currently \
-            mounted.
-        Returns 403 when the user doesn't have the ability to unmount the \
-            block device.
-        Returns 404 if the machine or block device is not found.
-        Returns 409 if the machine is not Ready or Allocated.
+        """@description-title Unmount a filesystem
+        @description Unmount the filesystem on block device.
+
+        @param (string) "{system_id}" [required=true] The machine system_id.
+        @param (string) "{id}" [required=true] The block device's id.
+
+        @success (http-status-code) "server-success" 200
+        @success (json) "success-json" A JSON object containing the updated
+        block device.
+        @success-example "success-json" [exkey=block-devs-unmount] placeholder
+        text
+
+        @error (http-status-code) "400" 400
+        @error (content) "problem" The block device is not formatted or
+        currently mounted.
+
+        @error (http-status-code) "403" 403
+        @error (content) "no-perms" The user does not have permissions to mount
+        the filesystem.
+
+        @error (http-status-code) "404" 404
+        @error (content) "not-found" The requested machine or block device is
+        not found.
+        @error-example "not-found"
+            Not Found
+
+        @error (http-status-code) "409" 409
+        @error (content) "not-ready" The requested machine is not ready.
         """
         device = BlockDevice.objects.get_block_device_or_404(
             system_id, id, request.user, NodePermission.edit)
@@ -442,12 +649,32 @@ class BlockDeviceHandler(OperationsHandler):
 
     @operation(idempotent=False)
     def set_boot_disk(self, request, system_id, id):
-        """Set this block device as the boot disk for the machine.
+        """@description-title Set boot disk
+        @description Set a block device as the boot disk for the machine.
+
+        @param (string) "{system_id}" [required=true] The machine system_id.
+        @param (string) "{id}" [required=true] The block device's id.
+
+        @success (http-status-code) "server-success" 200
+        @success (content) "success-content" Boot disk set.
+        @success-example "success-content"
+            OK
+
+        @error (http-status-code) "400" 400
+        @error (content) "problem" The block device is a virtual block device.
+
+        @error (http-status-code) "403" 403
+        @error (content) "no-perms" The user does not have permissions to set
+        the boot disk.
+
+        @error (http-status-code) "404" 404
+        @error (content) "not-found" The requested machine or block device is
+        not found.
+        @error-example "not-found"
+            Not Found
 
-        Returns 400 if the block device is a virtual block device.
-        Returns 404 if the machine or block device is not found.
-        Returns 403 if the user is not allowed to update the block device.
-        Returns 409 if the machine is not Ready or Allocated.
+        @error (http-status-code) "409" 409
+        @error (content) "not-ready" The requested machine is not ready.
         """
         device = BlockDevice.objects.get_block_device_or_404(
             system_id, id, request.user, NodePermission.admin)
diff --git a/src/maasserver/api/examples/nodes.json b/src/maasserver/api/examples/nodes.json
index 2f2b1bf..1efe0d1 100644
--- a/src/maasserver/api/examples/nodes.json
+++ b/src/maasserver/api/examples/nodes.json
@@ -2604,5 +2604,313 @@
   },
   "bcache-placeholder": {
     "message": "Information about this object is not available at this time."
+  },
+  "block-devs-read": [
+    {
+      "id_path": null,
+      "size": 3698265088,
+      "block_size": 512,
+      "tags": [
+        "tag-BGt1BR",
+        "tag-1Fm39m",
+        "tag-Hqbbak"
+      ],
+      "uuid": null,
+      "id": 1,
+      "available_size": 3698265088,
+      "filesystem": null,
+      "partitions": [],
+      "storage_pool": "pool_id-nHmvMI",
+      "used_size": 0,
+      "path": "/dev/disk/by-dname/name-86Ezga",
+      "partition_table_type": null,
+      "used_for": "Unused",
+      "type": "physical",
+      "name": "name-86Ezga",
+      "system_id": "y7388k",
+      "model": "model-sCuLNN",
+      "serial": "serial-ZKjZxn",
+      "resource_uri": "/MAAS/api/2.0/nodes/y7388k/blockdevices/1/"
+    },
+    {
+      "id_path": null,
+      "size": 1392376320,
+      "block_size": 512,
+      "tags": [
+        "tag-hZPKgU",
+        "tag-ImIubs",
+        "tag-yRv0Vm"
+      ],
+      "uuid": null,
+      "id": 2,
+      "available_size": 1392376320,
+      "filesystem": null,
+      "partitions": [],
+      "storage_pool": "pool_id-nHmvMI",
+      "used_size": 0,
+      "path": "/dev/disk/by-dname/name-EIcGBl",
+      "partition_table_type": null,
+      "used_for": "Unused",
+      "type": "physical",
+      "name": "name-EIcGBl",
+      "system_id": "y7388k",
+      "model": "model-QhVkKT",
+      "serial": "serial-3TaTIG",
+      "resource_uri": "/MAAS/api/2.0/nodes/y7388k/blockdevices/2/"
+    }
+  ],
+  "block-devs-create": {
+    "firmware_version": null,
+    "uuid": null,
+    "used_for": "Unused",
+    "used_size": 0,
+    "storage_pool": null,
+    "system_id": "y7388k",
+    "type": "physical",
+    "path": "/dev/disk/by-dname/newblockdevice",
+    "filesystem": null,
+    "id_path": "",
+    "partitions": [],
+    "tags": [],
+    "available_size": 1000000000,
+    "block_size": 1024000,
+    "model": "fakemodel",
+    "partition_table_type": null,
+    "name": "newblockdevice",
+    "size": 1000000000,
+    "serial": "123",
+    "id": 73,
+    "resource_uri": "/MAAS/api/2.0/nodes/y7388k/blockdevices/73/"
+  },
+  "block-devs-read-by-id": {
+    "firmware_version": null,
+    "system_id": "y7388k",
+    "block_size": 1024000,
+    "available_size": 1000000000,
+    "model": "fakemodel",
+    "serial": "123",
+    "used_size": 0,
+    "tags": [],
+    "partition_table_type": null,
+    "partitions": [],
+    "path": "/dev/disk/by-dname/newblockdevice",
+    "size": 1000000000,
+    "id_path": "",
+    "filesystem": null,
+    "storage_pool": null,
+    "name": "newblockdevice",
+    "used_for": "Unused",
+    "id": 73,
+    "type": "physical",
+    "uuid": null,
+    "resource_uri": "/MAAS/api/2.0/nodes/y7388k/blockdevices/73/"
+  },
+  "block-devs-update": {
+    "firmware_version": "firmware_version-WJ46L3",
+    "storage_pool": "pool_id-QkOjON",
+    "uuid": null,
+    "system_id": "thr3am",
+    "block_size": 4096,
+    "id_path": "",
+    "filesystem": null,
+    "used_for": "Unused",
+    "model": "model-5btVsu",
+    "used_size": 0,
+    "partition_table_type": null,
+    "id": 20,
+    "serial": "serial-SE3O1p",
+    "size": 2173730816,
+    "type": "physical",
+    "available_size": 2173730816,
+    "path": "/dev/disk/by-dname/newname",
+    "partitions": [],
+    "tags": [
+      "tag-WAlxSu",
+      "tag-p05xzW",
+      "tag-dwLYRY"
+    ],
+    "name": "newname",
+    "resource_uri": "/MAAS/api/2.0/nodes/thr3am/blockdevices/20/"
+  },
+  "block-devs-add-tag": {
+    "firmware_version": "firmware_version-WJ46L3",
+    "filesystem": null,
+    "available_size": 2173730816,
+    "model": "model-5btVsu",
+    "type": "physical",
+    "name": "newname",
+    "system_id": "thr3am",
+    "partition_table_type": null,
+    "partitions": [],
+    "size": 2173730816,
+    "id_path": "",
+    "block_size": 4096,
+    "uuid": null,
+    "used_size": 0,
+    "used_for": "Unused",
+    "tags": [
+      "tag-WAlxSu",
+      "tag-p05xzW",
+      "tag-dwLYRY",
+      "newtag"
+    ],
+    "storage_pool": "pool_id-QkOjON",
+    "path": "/dev/disk/by-dname/newname",
+    "id": 20,
+    "serial": "serial-SE3O1p",
+    "resource_uri": "/MAAS/api/2.0/nodes/thr3am/blockdevices/20/"
+  },
+  "block-devs-remove-tag": {
+    "firmware_version": "firmware_version-WJ46L3",
+    "used_for": "Unused",
+    "serial": "serial-SE3O1p",
+    "used_size": 0,
+    "partitions": [],
+    "block_size": 4096,
+    "available_size": 2173730816,
+    "type": "physical",
+    "path": "/dev/disk/by-dname/newname",
+    "storage_pool": "pool_id-QkOjON",
+    "id": 20,
+    "partition_table_type": null,
+    "model": "model-5btVsu",
+    "uuid": null,
+    "filesystem": null,
+    "name": "newname",
+    "tags": [
+      "tag-WAlxSu",
+      "tag-p05xzW",
+      "tag-dwLYRY"
+    ],
+    "id_path": "",
+    "size": 2173730816,
+    "system_id": "thr3am",
+    "resource_uri": "/MAAS/api/2.0/nodes/thr3am/blockdevices/20/"
+  },
+  "block-devs-format": {
+    "firmware_version": "firmware_version-WJ46L3",
+    "system_id": "thr3am",
+    "partitions": [],
+    "tags": [
+      "tag-WAlxSu",
+      "tag-p05xzW",
+      "tag-dwLYRY"
+    ],
+    "uuid": null,
+    "storage_pool": "pool_id-QkOjON",
+    "id": 20,
+    "type": "physical",
+    "filesystem": {
+      "fstype": "ext4",
+      "label": "",
+      "uuid": "fcc36eca-09fd-4c15-b339-c706ad3b75cf",
+      "mount_point": null,
+      "mount_options": null
+    },
+    "name": "newname",
+    "id_path": "",
+    "used_for": "Unmounted ext4 formatted filesystem",
+    "partition_table_type": null,
+    "model": "model-5btVsu",
+    "used_size": 2173730816,
+    "serial": "serial-SE3O1p",
+    "size": 2173730816,
+    "available_size": 0,
+    "block_size": 4096,
+    "path": "/dev/disk/by-dname/newname",
+    "resource_uri": "/MAAS/api/2.0/nodes/thr3am/blockdevices/20/"
+  },
+  "block-devs-unformat": {
+    "firmware_version": "firmware_version-WJ46L3",
+    "tags": [
+      "tag-WAlxSu",
+      "tag-p05xzW",
+      "tag-dwLYRY"
+    ],
+    "used_size": 0,
+    "uuid": null,
+    "system_id": "thr3am",
+    "id": 20,
+    "type": "physical",
+    "model": "model-5btVsu",
+    "id_path": "",
+    "size": 2173730816,
+    "available_size": 2173730816,
+    "path": "/dev/disk/by-dname/newname",
+    "used_for": "Unused",
+    "filesystem": null,
+    "partition_table_type": null,
+    "name": "newname",
+    "storage_pool": "pool_id-QkOjON",
+    "partitions": [],
+    "serial": "serial-SE3O1p",
+    "block_size": 4096,
+    "resource_uri": "/MAAS/api/2.0/nodes/thr3am/blockdevices/20/"
+  },
+  "block-devs-mount": {
+    "firmware_version": "firmware_version-WJ46L3",
+    "id": 20,
+    "available_size": 0,
+    "type": "physical",
+    "storage_pool": "pool_id-QkOjON",
+    "system_id": "thr3am",
+    "block_size": 4096,
+    "uuid": null,
+    "id_path": "",
+    "name": "newname",
+    "partitions": [],
+    "tags": [
+      "tag-WAlxSu",
+      "tag-p05xzW",
+      "tag-dwLYRY"
+    ],
+    "filesystem": {
+      "fstype": "ext4",
+      "label": "",
+      "uuid": "9a5860a2-497d-433b-98c3-e0059ad1545e",
+      "mount_point": "/media",
+      "mount_options": ""
+    },
+    "size": 2173730816,
+    "partition_table_type": null,
+    "model": "model-5btVsu",
+    "path": "/dev/disk/by-dname/newname",
+    "serial": "serial-SE3O1p",
+    "used_for": "ext4 formatted filesystem mounted at /media",
+    "used_size": 2173730816,
+    "resource_uri": "/MAAS/api/2.0/nodes/thr3am/blockdevices/20/"
+  },
+  "block-devs-unmount": {
+    "firmware_version": "firmware_version-WJ46L3",
+    "model": "model-5btVsu",
+    "size": 2173730816,
+    "partition_table_type": null,
+    "available_size": 0,
+    "used_for": "Unmounted ext4 formatted filesystem",
+    "id_path": "",
+    "name": "newname",
+    "id": 20,
+    "tags": [
+      "tag-WAlxSu",
+      "tag-p05xzW",
+      "tag-dwLYRY"
+    ],
+    "filesystem": {
+      "fstype": "ext4",
+      "label": "",
+      "uuid": "9a5860a2-497d-433b-98c3-e0059ad1545e",
+      "mount_point": null,
+      "mount_options": null
+    },
+    "partitions": [],
+    "storage_pool": "pool_id-QkOjON",
+    "used_size": 2173730816,
+    "block_size": 4096,
+    "system_id": "thr3am",
+    "serial": "serial-SE3O1p",
+    "type": "physical",
+    "path": "/dev/disk/by-dname/newname",
+    "uuid": null,
+    "resource_uri": "/MAAS/api/2.0/nodes/thr3am/blockdevices/20/"
   }
 }