Merge branch 'api-star-project' into 'master'

API: Star and unstar a project

Add two new endpoints `POST /projects/:id/star` and `POST /projects/:id/unstar` to star and unstar a project.

* Closes #12739


See merge request !3578

2 files changed, 127 insertions, 0 deletions

diff --git a/doc/api/README.md b/doc/api/README.md
index 7629ef294ac..3a8fa6cebd1 100644
--- a/doc/api/README.md
+++ b/doc/api/README.md
@@ -108,6 +108,7 @@ The following table shows the possible return codes for API requests.
 | ------------- | ----------- |
 | `200 OK` | The `GET`, `PUT` or `DELETE` request was successful, the resource(s) itself is returned as JSON. |
 | `201 Created` | The `POST` request was successful and the resource is returned as JSON. |
+| `304 Not Modified` | Indicates that the resource has not been modified since the last request. |
 | `400 Bad Request` | A required attribute of the API request is missing, e.g., the title of an issue is not given. |
 | `401 Unauthorized` | The user is not authenticated, a valid [user token](#authentication) is necessary. |
 | `403 Forbidden` | The request is not allowed, e.g., the user is not allowed to delete a project. |
diff --git a/doc/api/projects.md b/doc/api/projects.md
index ab716c229dc..de1faadebf5 100644
--- a/doc/api/projects.md
+++ b/doc/api/projects.md
@@ -491,6 +491,132 @@ Parameters:
 
 - `id` (required) - The ID of the project to be forked
 
+### Star a project
+
+Stars a given project. Returns status code `201` and the project on success and
+`304` if the project is already starred.
+
+```
+POST /projects/:id/star
+```
+
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id`      | integer | yes | The ID of the project |
+
+```bash
+curl -X POST -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/5/star"
+```
+
+Example response:
+
+```json
+{
+  "id": 3,
+  "description": null,
+  "default_branch": "master",
+  "public": false,
+  "visibility_level": 10,
+  "ssh_url_to_repo": "git@example.com:diaspora/diaspora-project-site.git",
+  "http_url_to_repo": "http://example.com/diaspora/diaspora-project-site.git",
+  "web_url": "http://example.com/diaspora/diaspora-project-site",
+  "tag_list": [
+    "example",
+    "disapora project"
+  ],
+  "name": "Diaspora Project Site",
+  "name_with_namespace": "Diaspora / Diaspora Project Site",
+  "path": "diaspora-project-site",
+  "path_with_namespace": "diaspora/diaspora-project-site",
+  "issues_enabled": true,
+  "open_issues_count": 1,
+  "merge_requests_enabled": true,
+  "builds_enabled": true,
+  "wiki_enabled": true,
+  "snippets_enabled": false,
+  "created_at": "2013-09-30T13: 46: 02Z",
+  "last_activity_at": "2013-09-30T13: 46: 02Z",
+  "creator_id": 3,
+  "namespace": {
+    "created_at": "2013-09-30T13: 46: 02Z",
+    "description": "",
+    "id": 3,
+    "name": "Diaspora",
+    "owner_id": 1,
+    "path": "diaspora",
+    "updated_at": "2013-09-30T13: 46: 02Z"
+  },
+  "archived": true,
+  "avatar_url": "http://example.com/uploads/project/avatar/3/uploads/avatar.png",
+  "shared_runners_enabled": true,
+  "forks_count": 0,
+  "star_count": 1
+}
+```
+
+### Unstar a project
+
+Unstars a given project. Returns status code `200` and the project on success
+and `304` if the project is not starred.
+
+```
+DELETE /projects/:id/star
+```
+
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id`      | integer | yes | The ID of the project |
+
+```bash
+curl -X DELETE -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/5/star"
+```
+
+Example response:
+
+```json
+{
+  "id": 3,
+  "description": null,
+  "default_branch": "master",
+  "public": false,
+  "visibility_level": 10,
+  "ssh_url_to_repo": "git@example.com:diaspora/diaspora-project-site.git",
+  "http_url_to_repo": "http://example.com/diaspora/diaspora-project-site.git",
+  "web_url": "http://example.com/diaspora/diaspora-project-site",
+  "tag_list": [
+    "example",
+    "disapora project"
+  ],
+  "name": "Diaspora Project Site",
+  "name_with_namespace": "Diaspora / Diaspora Project Site",
+  "path": "diaspora-project-site",
+  "path_with_namespace": "diaspora/diaspora-project-site",
+  "issues_enabled": true,
+  "open_issues_count": 1,
+  "merge_requests_enabled": true,
+  "builds_enabled": true,
+  "wiki_enabled": true,
+  "snippets_enabled": false,
+  "created_at": "2013-09-30T13: 46: 02Z",
+  "last_activity_at": "2013-09-30T13: 46: 02Z",
+  "creator_id": 3,
+  "namespace": {
+    "created_at": "2013-09-30T13: 46: 02Z",
+    "description": "",
+    "id": 3,
+    "name": "Diaspora",
+    "owner_id": 1,
+    "path": "diaspora",
+    "updated_at": "2013-09-30T13: 46: 02Z"
+  },
+  "archived": true,
+  "avatar_url": "http://example.com/uploads/project/avatar/3/uploads/avatar.png",
+  "shared_runners_enabled": true,
+  "forks_count": 0,
+  "star_count": 0
+}
+```
+
 ### Archive a project
 
 Archives the project if the user is either admin or the project owner of this project. This action is