also provide a payload for addWatcher

allow payloads to be templated (to some degree) as well

doc/apiv3-documentation.apib

@@ -101,7 +101,7 @@ Links to other resources in the API are represented uniformly by so called link
 | title     | Representative label for the resource                                    | String  |          |          |             |
 | templated | If true the `href` contains parts that need to be replaced by the client | Boolean |          |          | false       |
 | method    | The HTTP verb to use when requesting the resource                        | String  |          |          | GET         |
-| payload   | The exact payload to send in the request to achieve the desired result   | String  |          |          | unspecified |
+| payload   | The payload to send in the request to achieve the desired result         | String  |          |          | unspecified |
 
 All link objects *must* contain the `href` property, though it might be `null`. Thus the following is a valid
 link object:
@@ -115,7 +115,7 @@ For example a work package without an assignee will still have an assignee link,
 
 If a `title` is present, the client can display the title to the user when referring to the resource.
 
-Templated links are links that contain client replacable parts. Replaceable parts are enclosed in braces. For example
+Templated links are links that contain client replaceable parts. Replaceable parts are enclosed in braces. For example
 the link `api/v3/example/{id}` is not complete in itself, but the client needs to replace the string `{id}` itself.
 As of now the API does not indicate the valid replacement values.
 
@@ -123,7 +123,8 @@ The `method` indicates which HTTP verb the client *must* use when following the
 
 If a `payload` is specified, it needs to be sent as the body of the request to achieve the desired result (e.g. perform the
 action represented by the link). If no `payload` is specified, there is either no payload to send or there are multiple valid
-payloads.
+payloads. A payload might also be templated slightly. If the `templated` property is true, a payload might contain replaceable parts
+in its strings (e.g. `{ "href": "/api/v3/examples/{example_id}" }`).
 
 Note: When writing links (e.g. during a `PATCH` operation) only changes to `href` are accepted.
 Changes to all other properties will be **silently ignored**.
@@ -3179,21 +3180,21 @@ the human readable name of custom fields.*
                         "title": "Version 1"
                     },
                     "availableWatchers": {
-                        "href": "/api/v3/work_packages/1528/available_watchers",
-                        "title": "Available Watchers"
+                        "href": "/api/v3/work_packages/1528/available_watchers"
                     },
                     "watch": {
                         "href": "/api/v3/work_packages/1528/watchers",
                         "method": "post",
                         "payload": {
                             "user": { "href": "/api/v3/users/1" }
-                        },
-                        "title": "Watch work package"
+                        }
                     },
                     "addWatcher": {
-                        "href": "/api/v3/work_packages/1528/watchers{?user_id}",
+                        "href": "/api/v3/work_packages/1528/watchers",
                         "method": "post",
-                        "title": "Add watcher",
+                        "payload": {
+                            "user": { "href": "/api/v3/users/{user_id}" }
+                        },
                         "templated": true
                     },
                     "addRelation": {

lib/api/v3/work_packages/work_package_representer.rb

@@ -147,8 +147,9 @@ module API
 
         link :addWatcher do
           {
-            href: "#{api_v3_paths.work_package_watchers(represented.id)}{?user_id}",
+            href: api_v3_paths.work_package_watchers(represented.id),
             method: :post,
+            payload: { user: { href: api_v3_paths.user('{user_id}') } },
             templated: true
           } if current_user_allowed_to(:add_work_package_watchers)
         end