From 2c5bcf2e1b5b5574238555657296a8831b989d1e Mon Sep 17 00:00:00 2001 From: Zeger-Jan van de Weg Date: Wed, 23 Mar 2016 22:36:35 +0100 Subject: Add endpoints for archiving and unarchiving --- doc/api/projects.md | 164 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 164 insertions(+) (limited to 'doc/api') diff --git a/doc/api/projects.md b/doc/api/projects.md index 3703f4b327a..44d40235e9e 100644 --- a/doc/api/projects.md +++ b/doc/api/projects.md @@ -491,6 +491,170 @@ Parameters: - `id` (required) - The ID of the project to be forked +### Archive a project + +Archives a project if the user has the right access level to this project. This action is +idempotent, thus archiving an already archived project will not change the project. + +Status code 200 with the project as body is given when successful, in case the user doesn't +have the proper access rights, code 404 is returned. + +``` +PUT /projects/:id/archive +``` + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer | yes | The ID of the project | + +```bash +curl -X PUT -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/archive" +``` + +Example response: + +```json +{ + "id": 3, + "description": null, + "default_branch": "master", + "public": false, + "visibility_level": 0, + "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" + ], + "owner": { + "id": 3, + "name": "Diaspora", + "created_at": "2013-09-30T13: 46: 02Z" + }, + "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" + }, + "permissions": { + "project_access": { + "access_level": 10, + "notification_level": 3 + }, + "group_access": { + "access_level": 50, + "notification_level": 3 + } + }, + "archived": true, + "avatar_url": "http://example.com/uploads/project/avatar/3/uploads/avatar.png", + "shared_runners_enabled": true, + "forks_count": 0, + "star_count": 0, + "runners_token": "b8bc4a7a29eb76ea83cf79e4908c2b" +} +``` + +### Unarchive a project + +Unarchives a project if the user has the right access level to this project. This action is +idempotent, thus unarchiving an non-archived project will not change the project. + +Status code 200 with the project as body is given when successful, in case the user doesn't +have the proper access rights, code 404 is returned. + +``` +PUT /projects/:id/archive +``` + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer | yes | The ID of the project | + +```bash +curl -X PUT -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/unarchive" +``` + +Example response: + +```json +{ + "id": 3, + "description": null, + "default_branch": "master", + "public": false, + "visibility_level": 0, + "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" + ], + "owner": { + "id": 3, + "name": "Diaspora", + "created_at": "2013-09-30T13: 46: 02Z" + }, + "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" + }, + "permissions": { + "project_access": { + "access_level": 10, + "notification_level": 3 + }, + "group_access": { + "access_level": 50, + "notification_level": 3 + } + }, + "archived": false, + "avatar_url": "http://example.com/uploads/project/avatar/3/uploads/avatar.png", + "shared_runners_enabled": true, + "forks_count": 0, + "star_count": 0, + "runners_token": "b8bc4a7a29eb76ea83cf79e4908c2b" +} +``` + ### Remove project Removes a project including all associated resources (issues, merge requests etc.) -- cgit v1.2.1 From 3549d7c1d402c10c567c239b006132c45b0c0d1e Mon Sep 17 00:00:00 2001 From: Zeger-Jan van de Weg Date: Thu, 24 Mar 2016 13:36:45 +0100 Subject: PUT becomes POST on archiving endpoints Also the specs have a minor improvement. Mainly the access right spec. Changes are reflected in the docs --- doc/api/projects.md | 22 ++++++++++++---------- 1 file changed, 12 insertions(+), 10 deletions(-) (limited to 'doc/api') diff --git a/doc/api/projects.md b/doc/api/projects.md index 44d40235e9e..3a909a2bc87 100644 --- a/doc/api/projects.md +++ b/doc/api/projects.md @@ -493,14 +493,15 @@ Parameters: ### Archive a project -Archives a project if the user has the right access level to this project. This action is +Archives the project if the user is either admin or the project owner of this project. This action is idempotent, thus archiving an already archived project will not change the project. -Status code 200 with the project as body is given when successful, in case the user doesn't -have the proper access rights, code 404 is returned. +Status code 201 with the project as body is given when successful, in case the user doesn't +have the proper access rights, code 403 is returned. Status 404 is returned if the project +doesn't exist, or is hidden to the user. ``` -PUT /projects/:id/archive +POST /projects/:id/archive ``` | Attribute | Type | Required | Description | @@ -508,7 +509,7 @@ PUT /projects/:id/archive | `id` | integer | yes | The ID of the project | ```bash -curl -X PUT -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/archive" +curl -X POST -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/archive" ``` Example response: @@ -575,14 +576,15 @@ Example response: ### Unarchive a project -Unarchives a project if the user has the right access level to this project. This action is +Unarchives the project if the user is either admin or the project owner of this project. This action is idempotent, thus unarchiving an non-archived project will not change the project. -Status code 200 with the project as body is given when successful, in case the user doesn't -have the proper access rights, code 404 is returned. +Status code 201 with the project as body is given when successful, in case the user doesn't +have the proper access rights, code 403 is returned. Status 404 is returned if the project +doesn't exist, or is hidden to the user. ``` -PUT /projects/:id/archive +POST /projects/:id/archive ``` | Attribute | Type | Required | Description | @@ -590,7 +592,7 @@ PUT /projects/:id/archive | `id` | integer | yes | The ID of the project | ```bash -curl -X PUT -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/unarchive" +curl -X POST -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/unarchive" ``` Example response: -- cgit v1.2.1