Make subscription API more RESTful

2 files changed, 28 insertions, 27 deletions

diff --git a/doc/api/issues.md b/doc/api/issues.md
index 4f7d948eba1..42024becc36 100644
--- a/doc/api/issues.md
+++ b/doc/api/issues.md
@@ -408,13 +408,14 @@ Example response:
 
 ## Subscribe to an issue
 
-Subscribes to an issue to receive notifications. If the operation is successful,
-status code `201` together with the updated issue is returned. If the user is
-already subscribed to the issue, the status code `304` is returned. If the
-project or issue is not found, status code `404` is returned.
+Subscribes the authenticated user to an issue to receive notifications. If the
+operation is successful, status code `201` together with the updated issue is
+returned. If the user is already subscribed to the issue, the status code `304`
+is returned. If the project or issue is not found, status code `404` is
+returned.
 
 ```
-POST /projects/:id/issues/:issue_id/subscribe
+POST /projects/:id/issues/:issue_id/subscription
 ```
 
 | Attribute | Type | Required | Description |
@@ -423,7 +424,7 @@ POST /projects/:id/issues/:issue_id/subscribe
 | `issue_id` | integer | yes | The ID of a project's issue |
 
 ```bash
-curl -X POST -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/5/issues/93/subscribe
+curl -X POST -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/5/issues/93/subscription
 ```
 
 Example response:
@@ -461,14 +462,14 @@ Example response:
 
 ## Unsubscribe from an issue
 
-Unsubscribes from an issue to not receive notifications from that issue. If the
-operation is successful, status code `201` together with the updated issue is
-returned. If the user is not subscribed to the issue, the status code `304`
-is returned. If the project or issue is not found, status code `404` is
-returned.
+Unsubscribes the authenticated user from the issue to not receive notifications
+from it. If the operation is successful, status code `200` together with the
+updated issue is returned. If the user is not subscribed to the issue, the
+status code `304` is returned. If the project or issue is not found, status code
+`404` is returned.
 
 ```
-POST /projects/:id/issues/:issue_id/unsubscribe
+DELETE /projects/:id/issues/:issue_id/subscription
 ```
 
 | Attribute | Type | Required | Description |
@@ -477,7 +478,7 @@ POST /projects/:id/issues/:issue_id/unsubscribe
 | `issue_id` | integer | yes | The ID of a project's issue |
 
 ```bash
-curl -X POST -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/5/issues/93/unsubscribe
+curl -X DELETE -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/5/issues/93/subscription
 ```
 
 Example response:
diff --git a/doc/api/merge_requests.md b/doc/api/merge_requests.md
index 16cb8926265..3c18ebfa31e 100644
--- a/doc/api/merge_requests.md
+++ b/doc/api/merge_requests.md
@@ -609,14 +609,14 @@ Example response:
 
 ## Subscribe to a merge request
 
-Subscribes to a merge request to receive notification. If the operation is
-successful, status code `201` together with the updated merge request is
-returned. If the user is already subscribed to the merge request, the status
-code `304` is returned. If the project or merge request is not found, status
-code `404` is returned.
+Subscribes the authenticated user to a merge request to receive notification. If
+the operation is successful, status code `201` together with the updated merge
+request is returned. If the user is already subscribed to the merge request, the
+status code `304` is returned. If the project or merge request is not found,
+status code `404` is returned.
 
 ```
-POST /projects/:id/merge_requests/:merge_request_id/subscribe
+POST /projects/:id/merge_requests/:merge_request_id/subscription
 ```
 
 | Attribute | Type | Required | Description |
@@ -625,7 +625,7 @@ POST /projects/:id/merge_requests/:merge_request_id/subscribe
 | `merge_request_id` | integer | yes   | The ID of the merge request |
 
 ```bash
-curl -X POST -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/5/merge_requests/17/subscribe
+curl -X POST -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/5/merge_requests/17/subscription
 ```
 
 Example response:
@@ -682,14 +682,14 @@ Example response:
 ```
 ## Unsubscribe from a merge request
 
-Unsubscribes from a merge request to not receive notifications from that merge
-request. If the operation is successful, status code `201` together with the
-updated merge request is returned. If the user is not subscribed to the merge
-request, the status code `304` is returned. If the project or merge request is
-not found, status code `404` is returned.
+Unsubscribes the authenticated user from a merge request to not receive
+notifications from that merge request. If the operation is successful, status
+code `200` together with the updated merge request is returned. If the user is
+not subscribed to the merge request, the status code `304` is returned. If the
+project or merge request is not found, status code `404` is returned.
 
 ```
-POST /projects/:id/merge_requests/:merge_request_id/unsubscribe
+DELETE /projects/:id/merge_requests/:merge_request_id/subscription
 ```
 
 | Attribute | Type | Required | Description |
@@ -698,7 +698,7 @@ POST /projects/:id/merge_requests/:merge_request_id/unsubscribe
 | `merge_request_id` | integer | yes   | The ID of the merge request |
 
 ```bash
-curl -X POST -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/5/merge_requests/17/subscribe
+curl -X DELETE -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v3/projects/5/merge_requests/17/subscription
 ```
 
 Example response: