Add latest changes from gitlab-org/gitlab@master

1 files changed, 85 insertions, 1 deletions

diff --git a/doc/api/users.md b/doc/api/users.md
index d0907008129..60db3be5e88 100644
--- a/doc/api/users.md
+++ b/doc/api/users.md
@@ -274,7 +274,9 @@ Parameters:
   "twitter": "",
   "website_url": "",
   "organization": "",
-  "job_title": "Operations Specialist"
+  "job_title": "Operations Specialist",
+  "followers": 1,
+  "following": 1
 }
 ```
 
@@ -685,6 +687,88 @@ Example responses
 }
 ```
 
+## User Follow
+
+### Follow and unfollow users
+
+Follow a user.
+
+```plaintext
+POST /users/:id/follow
+```
+
+Unfollow a user.
+
+```plaintext
+POST /users/:id/unfollow
+```
+
+| Attribute | Type    | Required | Description                  |
+| --------- | ------- | -------- | ---------------------------- |
+| `id`      | integer | yes      | The ID of the user to follow |
+
+```shell
+curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/users/3/follow"
+```
+
+Example response:
+
+```json
+{
+  "id": 1,
+  "username": "john_smith",
+  "name": "John Smith",
+  "state": "active",
+  "avatar_url": "http://localhost:3000/uploads/user/avatar/1/cd8.jpeg",
+  "web_url": "http://localhost:3000/john_smith"
+}
+```
+
+### Followers and following
+
+Get the followers of a user.
+
+```plaintext
+GET /users/:id/followers
+```
+
+Get the list of users being followed.
+
+```plaintext
+GET /users/:id/following
+```
+
+| Attribute | Type    | Required | Description                  |
+| --------- | ------- | -------- | ---------------------------- |
+| `id`      | integer | yes      | The ID of the user to follow |
+
+```shell
+curl --request GET --header "PRIVATE-TOKEN: <your_access_token>"  "https://gitlab.example.com/users/3/followers"
+```
+
+Example response:
+
+```json
+[
+  {
+    "id": 2,
+    "name": "Lennie Donnelly",
+    "username": "evette.kilback",
+    "state": "active",
+    "avatar_url": "https://www.gravatar.com/avatar/7955171a55ac4997ed81e5976287890a?s=80&d=identicon",
+    "web_url": "http://127.0.0.1:3000/evette.kilback"
+  },
+  {
+    "id": 4,
+    "name": "Serena Bradtke",
+    "username": "cammy",
+    "state": "active",
+    "avatar_url": "https://www.gravatar.com/avatar/a2daad869a7b60d3090b7b9bef4baf57?s=80&d=identicon",
+    "web_url": "http://127.0.0.1:3000/cammy"
+  }
+]
+```
+
 ## User counts
 
 Get the counts (same as in top right menu) of the currently signed in user.