From 55360c6f32ce9bf264963b8fc0c51b42d9e691f2 Mon Sep 17 00:00:00 2001 From: Jan Sandbrink Date: Thu, 11 Jun 2015 10:34:32 +0200 Subject: [PATCH] also provide a payload for addWatcher allow payloads to be templated (to some degree) as well --- doc/apiv3-documentation.apib | 19 ++++++++++--------- .../work_packages/work_package_representer.rb | 3 ++- 2 files changed, 12 insertions(+), 10 deletions(-) diff --git a/doc/apiv3-documentation.apib b/doc/apiv3-documentation.apib index 37f2ebf46c..004e3af87c 100644 --- a/doc/apiv3-documentation.apib +++ b/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": { diff --git a/lib/api/v3/work_packages/work_package_representer.rb b/lib/api/v3/work_packages/work_package_representer.rb index 8c32d3c5f8..46808892d4 100644 --- a/lib/api/v3/work_packages/work_package_representer.rb +++ b/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