vatesfr · julien-f · Nov 23, 2023 · Nov 21, 2023 · Nov 21, 2023
diff --git a/CHANGELOG.unreleased.md b/CHANGELOG.unreleased.md
@@ -12,6 +12,7 @@
 - [Restore] Show source remote and restoration time on a restored VM (PR [#7186](https://github.com/vatesfr/xen-orchestra/pull/7186))
 - [Backup/Import] Show disk import status during Incremental Replication or restoration of Incremental Backup (PR [#7171](https://github.com/vatesfr/xen-orchestra/pull/7171))
 - [VM Creation] Added ISO option in new VM form when creating from template with a disk [#3464](https://github.com/vatesfr/xen-orchestra/issues/3464) (PR [#7166](https://github.com/vatesfr/xen-orchestra/pull/7166))
+- [REST API] `tags` property can be updated (PR [#7196](https://github.com/vatesfr/xen-orchestra/pull/7196))
 
 ### Bug fixes
 
@@ -43,7 +44,8 @@
 - @xen-orchestra/cr-seed-cli major
 - @xen-orchestra/vmware-explorer patch
 - xen-api major
-- xo-server patch
+- xo-cli minor
+- xo-server minor
 - xo-server-netbox minor
 - xo-vmdk-to-vhd patch
 - xo-web minor

diff --git a/docs/restapi.md b/docs/restapi.md
@@ -123,7 +123,7 @@ Content-Type: application/x-ndjson
 
 ## Properties update
 
-> This feature is restricted to `name_label` and `name_description` at the moment.
+> This feature is restricted to `name_label`, `name_description` and `tags` at the moment.
 
 ```sh
 curl \
@@ -135,6 +135,30 @@ curl \
   'https://xo.example.org/rest/v0/vms/770aa52a-fd42-8faf-f167-8c5c4a237cac'
 ```
 
+### Collections
+
+For collection properties, like `tags`, it can be more practical to touch a single item without impacting the others.
+
+An item can be created with `PUT <collection>/<item id>` and can be destroyed with `DELETE <collection>/<item id>`.
+
+Adding a tag:
+
+```sh
+curl \
+-X PUT \
+-b authenticationToken=KQxQdm2vMiv7jBIK0hgkmgxKzemd8wSJ7ugFGKFkTbs \
+'https://xo.example.org/rest/v0/vms/770aa52a-fd42-8faf-f167-8c5c4a237cac/tags/My%20tag'
+```
+
+Removing a tag:
+
+```sh
+curl \
+  -X DELETE \
+  -b authenticationToken=KQxQdm2vMiv7jBIK0hgkmgxKzemd8wSJ7ugFGKFkTbs \
+  'https://xo.example.org/rest/v0/vms/770aa52a-fd42-8faf-f167-8c5c4a237cac/tags/My%20tag'
+```
+
 ## VM and VDI destruction
 
 For a VM:

diff --git a/packages/xo-cli/.USAGE.md b/packages/xo-cli/.USAGE.md
@@ -50,6 +50,7 @@ Usage:
 
     Examples:
       xo-cli rest del tasks/<task id>
+      xo-cli rest del vms/<vm id>/tags/<tag>
 
   xo-cli rest get <collection> [fields=<fields>] [filter=<filter>] [limit=<limit>]
     List objects in a REST API collection.
@@ -122,6 +123,18 @@ Usage:
     Examples:
       xo-cli rest post tasks/<task id>/actions/abort
       xo-cli rest post vms/<VM UUID>/actions/snapshot name_label='My snapshot'
+
+  xo-cli rest put <collection>/<item id> <name>=<value>...
+    Put a item in a collection
+
+    <collection>/<item id>
+      Full path of the item to add
+
+    <name>=<value>...
+      Properties of the item
+
+    Examples:
+      xo-cli rest put vms/<vm id>/tags/<tag>
 ```
 
 #### Register your XO instance

diff --git a/packages/xo-cli/README.md b/packages/xo-cli/README.md
@@ -68,6 +68,7 @@ Usage:
 
     Examples:
       xo-cli rest del tasks/<task id>
+      xo-cli rest del vms/<vm id>/tags/<tag>
 
   xo-cli rest get <collection> [fields=<fields>] [filter=<filter>] [limit=<limit>]
     List objects in a REST API collection.
@@ -140,6 +141,18 @@ Usage:
     Examples:
       xo-cli rest post tasks/<task id>/actions/abort
       xo-cli rest post vms/<VM UUID>/actions/snapshot name_label='My snapshot'
+
+  xo-cli rest put <collection>/<item id> <name>=<value>...
+    Put a item in a collection
+
+    <collection>/<item id>
+      Full path of the item to add
+
+    <name>=<value>...
+      Properties of the item
+
+    Examples:
+      xo-cli rest put vms/<vm id>/tags/<tag>
 ```
 
 #### Register your XO instance

diff --git a/packages/xo-cli/index.mjs b/packages/xo-cli/index.mjs
@@ -274,6 +274,7 @@ const help = wrap(
 
     Examples:
       $name rest del tasks/<task id>
+      $name rest del vms/<vm id>/tags/<tag>
 
   $name rest get <collection> [fields=<fields>] [filter=<filter>] [limit=<limit>]
     List objects in a REST API collection.
@@ -347,6 +348,18 @@ const help = wrap(
       $name rest post tasks/<task id>/actions/abort
       $name rest post vms/<VM UUID>/actions/snapshot name_label='My snapshot'
 
+  $name rest put <collection>/<item id> <name>=<value>...
+    Put a item in a collection
+
+    <collection>/<item id>
+      Full path of the item to add
+
+    <name>=<value>...
+      Properties of the item
+
+    Examples:
+      $name rest put vms/<vm id>/tags/<tag>
+
 $name v$version`.replace(/<([^>]+)>|\$(\w+)/g, function (_, arg, key) {
       if (arg) {
         return '<' + chalk.yellow(arg) + '>'

diff --git a/packages/xo-cli/rest.mjs b/packages/xo-cli/rest.mjs
@@ -112,6 +112,18 @@ const COMMANDS = {
 
     return stripPrefix(await response.text())
   },
+
+  async put([path, ...params]) {
+    const response = await this.exec(path, {
+      body: JSON.stringify(parseParams(params)),
+      headers: {
+        'content-type': 'application/json',
+      },
+      method: 'PUT',
+    })
+
+    return stripPrefix(await response.text())
+  },
 }
 
 export async function rest(args) {

diff --git a/packages/xo-server/docs/rest-api.md b/packages/xo-server/docs/rest-api.md
@@ -119,7 +119,7 @@ Content-Type: application/x-ndjson
 
 ## Properties update
 
-> This feature is restricted to `name_label` and `name_description` at the moment.
+> This feature is restricted to `name_label`, `name_description` and `tags` at the moment.
 
 ```sh
 curl \
@@ -131,6 +131,30 @@ curl \
   'https://xo.company.lan/rest/v0/vms/770aa52a-fd42-8faf-f167-8c5c4a237cac'
 ```
 
+### Collections
+
+For collection properties, like `tags`, it can be more practical to touch a single item without impacting the others.
+
+An item can be created with `PUT <collection>/<item id>` and can be destroyed with `DELETE <collection>/<item id>`.
+
+Adding a tag:
+
+```sh
+curl \
+-X PUT \
+-b authenticationToken=KQxQdm2vMiv7jBIK0hgkmgxKzemd8wSJ7ugFGKFkTbs \
+'https://xo.company.lan/rest/v0/vms/770aa52a-fd42-8faf-f167-8c5c4a237cac/tags/My%20tag'
+```
+
+Removing a tag:
+
+```sh
+curl \
+  -X DELETE \
+  -b authenticationToken=KQxQdm2vMiv7jBIK0hgkmgxKzemd8wSJ7ugFGKFkTbs \
+  'https://xo.company.lan/rest/v0/vms/770aa52a-fd42-8faf-f167-8c5c4a237cac/tags/My%20tag'
+```
+
 ## VM destruction
 
 ```sh

diff --git a/packages/xo-server/src/xo-mixins/rest-api.mjs b/packages/xo-server/src/xo-mixins/rest-api.mjs
@@ -479,24 +479,43 @@ export default class RestApi {
 
       res.json(result)
     })
-    api.patch(
-      '/:collection/:object',
-      json(),
-      wrap(async (req, res) => {
-        const obj = req.xapiObject
-
-        const promises = []
-        const { body } = req
-        for (const key of ['name_description', 'name_label']) {
-          const value = body[key]
-          if (value !== undefined) {
-            promises.push(obj['set_' + key](value))
+    api
+      .patch(
+        '/:collection/:object',
+        json(),
+        wrap(async (req, res) => {
+          const obj = req.xapiObject
+
+          const promises = []
+          const { body } = req
+
+          for (const key of ['name_description', 'name_label', 'tags']) {
+            const value = body[key]
+            if (value !== undefined) {
+              promises.push(obj['set_' + key](value))
+            }
           }
-        }
-        await promises
-        res.sendStatus(204)
-      })
-    )
+
+          await promises
+          res.sendStatus(204)
+        })
+      )
+      .delete(
+        '/:collection/:object/tags/:tag',
+        wrap(async (req, res) => {
+          await req.xapiObject.$call('remove_tags', req.params.tag)
+
+          res.sendStatus(204)
+        })
+      )
+      .put(
+        '/:collection/:object/tags/:tag',
+        wrap(async (req, res) => {
+          await req.xapiObject.$call('add_tags', req.params.tag)
+
+          res.sendStatus(204)
+        })
+      )
 
     api.get(
       '/:collection/:object/tasks',