From 0395c47193b3bbf6b4f060f28c9f632580313a35 Mon Sep 17 00:00:00 2001 From: Yorick Peterse Date: Mon, 10 Jul 2017 17:43:57 +0200 Subject: Migrate events into a new format This commit migrates events data in such a way that push events are stored much more efficiently. This is done by creating a shadow table called "events_for_migration", and a table called "push_event_payloads" which is used for storing push data of push events. The background migration in this commit will copy events from the "events" table into the "events_for_migration" table, push events in will also have a row created in "push_event_payloads". This approach allows us to reclaim space in the next release by simply swapping the "events" and "events_for_migration" tables, then dropping the old events (now "events_for_migration") table. The new table structure is also optimised for storage space, and does not include the unused "title" column nor the "data" column (since this data is moved to "push_event_payloads"). == Newly Created Events Newly created events are inserted into both "events" and "events_for_migration", both using the exact same primary key value. The table "push_event_payloads" in turn has a foreign key to the _shadow_ table. This removes the need for recreating and validating the foreign key after swapping the tables. Since the shadow table also has a foreign key to "projects.id" we also don't have to worry about orphaned rows. This approach however does require some additional storage as we're duplicating a portion of the events data for at least 1 release. The exact amount is hard to estimate, but for GitLab.com this is expected to be between 10 and 20 GB at most. The background migration in this commit deliberately does _not_ update the "events" table as doing so would put a lot of pressure on PostgreSQL's auto vacuuming system. == Supporting Both Old And New Events Application code has also been adjusted to support push events using both the old and new data formats. This is done by creating a PushEvent class which extends the regular Event class. Using Rails' Single Table Inheritance system we can ensure the right class is used for the right data, which in this case is based on the value of `events.action`. To support displaying old and new data at the same time the PushEvent class re-defines a few methods of the Event class, falling back to their original implementations for push events in the old format. Once all existing events have been migrated the various push event related methods can be removed from the Event model, and the calls to `super` can be removed from the methods in the PushEvent model. The UI and event atom feed have also been slightly changed to better handle this new setup, fortunately only a few changes were necessary to make this work. == API Changes The API only displays push data of events in the new format. Supporting both formats in the API is a bit more difficult compared to the UI. Since the old push data was not really well documented (apart from one example that used an incorrect "action" nmae) I decided that supporting both was not worth the effort, especially since events will be migrated in a few days _and_ new events are created in the correct format. --- doc/api/events.md | 42 +++++++++--------------------------------- 1 file changed, 9 insertions(+), 33 deletions(-) (limited to 'doc/api') diff --git a/doc/api/events.md b/doc/api/events.md index 3d5170f3f1e..129af0afa35 100644 --- a/doc/api/events.md +++ b/doc/api/events.md @@ -79,7 +79,6 @@ Example response: "target_id":160, "target_type":"Issue", "author_id":25, - "data":null, "target_title":"Qui natus eos odio tempore et quaerat consequuntur ducimus cupiditate quis.", "created_at":"2017-02-09T10:43:19.667Z", "author":{ @@ -99,7 +98,6 @@ Example response: "target_id":159, "target_type":"Issue", "author_id":21, - "data":null, "target_title":"Nostrum enim non et sed optio illo deleniti non.", "created_at":"2017-02-09T10:43:19.426Z", "author":{ @@ -151,7 +149,6 @@ Example response: "target_id": 830, "target_type": "Issue", "author_id": 1, - "data": null, "target_title": "Public project search field", "author": { "name": "Dmitriy Zaporozhets", @@ -166,7 +163,7 @@ Example response: { "title": null, "project_id": 15, - "action_name": "opened", + "action_name": "pushed", "target_id": null, "target_type": null, "author_id": 1, @@ -179,31 +176,14 @@ Example response: "web_url": "http://localhost:3000/root" }, "author_username": "john", - "data": { - "before": "50d4420237a9de7be1304607147aec22e4a14af7", - "after": "c5feabde2d8cd023215af4d2ceeb7a64839fc428", - "ref": "refs/heads/master", - "user_id": 1, - "user_name": "Dmitriy Zaporozhets", - "repository": { - "name": "gitlabhq", - "url": "git@dev.gitlab.org:gitlab/gitlabhq.git", - "description": "GitLab: self hosted Git management software. \r\nDistributed under the MIT License.", - "homepage": "https://dev.gitlab.org/gitlab/gitlabhq" - }, - "commits": [ - { - "id": "c5feabde2d8cd023215af4d2ceeb7a64839fc428", - "message": "Add simple search to projects in public area", - "timestamp": "2013-05-13T18:18:08+00:00", - "url": "https://dev.gitlab.org/gitlab/gitlabhq/commit/c5feabde2d8cd023215af4d2ceeb7a64839fc428", - "author": { - "name": "Dmitriy Zaporozhets", - "email": "dmitriy.zaporozhets@gmail.com" - } - } - ], - "total_commits_count": 1 + "push_data": { + "commit_count": 1, + "action": "pushed", + "ref_type": "branch", + "commit_from": "50d4420237a9de7be1304607147aec22e4a14af7", + "commit_to": "c5feabde2d8cd023215af4d2ceeb7a64839fc428", + "ref": "master", + "commit_title": "Add simple search to projects in public area" }, "target_title": null }, @@ -214,7 +194,6 @@ Example response: "target_id": 840, "target_type": "Issue", "author_id": 1, - "data": null, "target_title": "Finish & merge Code search PR", "author": { "name": "Dmitriy Zaporozhets", @@ -233,7 +212,6 @@ Example response: "target_id": 1312, "target_type": "Note", "author_id": 1, - "data": null, "target_title": null, "created_at": "2015-12-04T10:33:58.089Z", "note": { @@ -305,7 +283,6 @@ Example response: "target_iid":160, "target_type":"Issue", "author_id":25, - "data":null, "target_title":"Qui natus eos odio tempore et quaerat consequuntur ducimus cupiditate quis.", "created_at":"2017-02-09T10:43:19.667Z", "author":{ @@ -326,7 +303,6 @@ Example response: "target_iid":159, "target_type":"Issue", "author_id":21, - "data":null, "target_title":"Nostrum enim non et sed optio illo deleniti non.", "created_at":"2017-02-09T10:43:19.426Z", "author":{ -- cgit v1.2.1 From 73ffcb88e9eadf1695cde71685835ec7216d5b1c Mon Sep 17 00:00:00 2001 From: Shinya Maeda Date: Fri, 18 Aug 2017 08:48:24 +0000 Subject: Update project_snippets.md --- doc/api/project_snippets.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/api') diff --git a/doc/api/project_snippets.md b/doc/api/project_snippets.md index d74398c6e65..24c8ff5fa7a 100644 --- a/doc/api/project_snippets.md +++ b/doc/api/project_snippets.md @@ -150,4 +150,4 @@ Example response: } ``` -[ce-[ce-29508]: https://gitlab.com/gitlab-org/gitlab-ce/issues/29508]: https://gitlab.com/gitlab-org/gitlab-ce/issues/29508 +[ce-29508]: https://gitlab.com/gitlab-org/gitlab-ce/issues/29508 -- cgit v1.2.1 From 1ffd0c8562922de0e70eef2faf71108e0eecbb51 Mon Sep 17 00:00:00 2001 From: Zeger-Jan van de Weg Date: Fri, 18 Aug 2017 10:14:13 +0200 Subject: Remove CI API v1 This API was mainly for internal usage, and has been moved to the general API: APIv4. The endpoints have been deprecated since 9.0, and won't see 10.0. :) --- doc/api/ci/README.md | 24 --------- doc/api/ci/builds.md | 147 -------------------------------------------------- doc/api/ci/lint.md | 51 ------------------ doc/api/ci/runners.md | 59 -------------------- 4 files changed, 281 deletions(-) delete mode 100644 doc/api/ci/README.md delete mode 100644 doc/api/ci/builds.md delete mode 100644 doc/api/ci/lint.md delete mode 100644 doc/api/ci/runners.md (limited to 'doc/api') diff --git a/doc/api/ci/README.md b/doc/api/ci/README.md deleted file mode 100644 index 96a281e27c8..00000000000 --- a/doc/api/ci/README.md +++ /dev/null @@ -1,24 +0,0 @@ -# GitLab CI API - -## Purpose - -The main purpose of GitLab CI API is to provide the necessary data and context -for GitLab CI Runners. - -All relevant information about the consumer API can be found in a -[separate document](../../api/README.md). - -## API Prefix - -The current CI API prefix is `/ci/api/v1`. - -You need to prepend this prefix to all examples in this documentation, like: - -```bash -GET /ci/api/v1/builds/:id/artifacts -``` - -## Resources - -- [Builds](builds.md) -- [Runners](runners.md) diff --git a/doc/api/ci/builds.md b/doc/api/ci/builds.md deleted file mode 100644 index c8374d94716..00000000000 --- a/doc/api/ci/builds.md +++ /dev/null @@ -1,147 +0,0 @@ -# Builds API - -API used by runners to receive and update builds. - ->**Note:** -This API is intended to be used only by Runners as their own -communication channel. For the consumer API see the -[Jobs API](../jobs.md). - -## Authentication - -This API uses two types of authentication: - -1. Unique Runner's token which is the token assigned to the Runner after it - has been registered. - -2. Using the build authorization token. - This is project's CI token that can be found under the **Builds** section of - a project's settings. The build authorization token can be passed as a - parameter or a value of `BUILD-TOKEN` header. - -These two methods of authentication are interchangeable. - -## Builds - -### Runs oldest pending build by runner - -``` -POST /ci/api/v1/builds/register -``` - -| Attribute | Type | Required | Description | -|-----------|---------|----------|---------------------| -| `token` | string | yes | Unique runner token | - - -``` -curl --request POST "https://gitlab.example.com/ci/api/v1/builds/register" --form "token=t0k3n" -``` - -**Responses:** - -| Status | Data |Description | -|--------|------|---------------------------------------------------------------------------| -| `201` | yes | When a build is scheduled for a runner | -| `204` | no | When no builds are scheduled for a runner (for GitLab Runner >= `v1.3.0`) | -| `403` | no | When invalid token is used or no token is sent | -| `404` | no | When no builds are scheduled for a runner (for GitLab Runner < `v1.3.0`) **or** when the runner is set to `paused` in GitLab runner's configuration page | - -### Update details of an existing build - -``` -PUT /ci/api/v1/builds/:id -``` - -| Attribute | Type | Required | Description | -|-----------|---------|----------|----------------------| -| `id` | integer | yes | The ID of a project | -| `token` | string | yes | Unique runner token | -| `state` | string | no | The state of a build | -| `trace` | string | no | The trace of a build | - -``` -curl --request PUT "https://gitlab.example.com/ci/api/v1/builds/1234" --form "token=t0k3n" --form "state=running" --form "trace=Running git clone...\n" -``` - -### Incremental build trace update - -Using this method you need to send trace content as a request body. You also need to provide the `Content-Range` header -with a range of sent trace part. Note that you need to send parts in the proper order, so the begining of the part -must start just after the end of the previous part. If you provide the wrong part, then GitLab CI API will return `416 -Range Not Satisfiable` response with a header `Range: 0-X`, where `X` is the current trace length. - -For example, if you receive `Range: 0-11` in the response, then your next part must contain a `Content-Range: 11-...` -header and a trace part covered by this range. - -For a valid update API will return `202` response with: -* `Build-Status: {status}` header containing current status of the build, -* `Range: 0-{length}` header with the current trace length. - -``` -PATCH /ci/api/v1/builds/:id/trace.txt -``` - -Parameters: - -| Attribute | Type | Required | Description | -|-----------|---------|----------|----------------------| -| `id` | integer | yes | The ID of a build | - -Headers: - -| Attribute | Type | Required | Description | -|-----------------|---------|----------|-----------------------------------| -| `BUILD-TOKEN` | string | yes | The build authorization token | -| `Content-Range` | string | yes | Bytes range of trace that is sent | - -``` -curl --request PATCH "https://gitlab.example.com/ci/api/v1/builds/1234/trace.txt" --header "BUILD-TOKEN=build_t0k3n" --header "Content-Range=0-21" --data "Running git clone...\n" -``` - - -### Upload artifacts to build - -``` -POST /ci/api/v1/builds/:id/artifacts -``` - -| Attribute | Type | Required | Description | -|-----------|---------|----------|-------------------------------| -| `id` | integer | yes | The ID of a build | -| `token` | string | yes | The build authorization token | -| `file` | mixed | yes | Artifacts file | - -``` -curl --request POST "https://gitlab.example.com/ci/api/v1/builds/1234/artifacts" --form "token=build_t0k3n" --form "file=@/path/to/file" -``` - -### Download the artifacts file from build - -``` -GET /ci/api/v1/builds/:id/artifacts -``` - -| Attribute | Type | Required | Description | -|-----------|---------|----------|-------------------------------| -| `id` | integer | yes | The ID of a build | -| `token` | string | yes | The build authorization token | - -``` -curl "https://gitlab.example.com/ci/api/v1/builds/1234/artifacts" --form "token=build_t0k3n" -``` - -### Remove the artifacts file from build - -``` -DELETE /ci/api/v1/builds/:id/artifacts -``` - -| Attribute | Type | Required | Description | -|-----------|---------|----------|-------------------------------| -| ` id` | integer | yes | The ID of a build | -| `token` | string | yes | The build authorization token | - -``` -curl --request DELETE "https://gitlab.example.com/ci/api/v1/builds/1234/artifacts" --form "token=build_t0k3n" -``` diff --git a/doc/api/ci/lint.md b/doc/api/ci/lint.md deleted file mode 100644 index e4a6dc809b1..00000000000 --- a/doc/api/ci/lint.md +++ /dev/null @@ -1,51 +0,0 @@ -# Validate the .gitlab-ci.yml (API) - -> [Introduced][ce-5953] in GitLab 8.12. - -Checks if your .gitlab-ci.yml file is valid. - -``` -POST ci/lint -``` - -| Attribute | Type | Required | Description | -| ---------- | ------- | -------- | -------- | -| `content` | string | yes | the .gitlab-ci.yaml content| - -```bash -curl --header "Content-Type: application/json" https://gitlab.example.com/api/v4/ci/lint --data '{"content": "{ \"image\": \"ruby:2.1\", \"services\": [\"postgres\"], \"before_script\": [\"gem install bundler\", \"bundle install\", \"bundle exec rake db:create\"], \"variables\": {\"DB_NAME\": \"postgres\"}, \"types\": [\"test\", \"deploy\", \"notify\"], \"rspec\": { \"script\": \"rake spec\", \"tags\": [\"ruby\", \"postgres\"], \"only\": [\"branches\"]}}"}' -``` - -Be sure to copy paste the exact contents of `.gitlab-ci.yml` as YAML is very picky about indentation and spaces. - -Example responses: - -* Valid content: - - ```json - { - "status": "valid", - "errors": [] - } - ``` - -* Invalid content: - - ```json - { - "status": "invalid", - "errors": [ - "variables config should be a hash of key value pairs" - ] - } - ``` - -* Without the content attribute: - - ```json - { - "error": "content is missing" - } - ``` - -[ce-5953]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5953 diff --git a/doc/api/ci/runners.md b/doc/api/ci/runners.md deleted file mode 100644 index 342c039dad8..00000000000 --- a/doc/api/ci/runners.md +++ /dev/null @@ -1,59 +0,0 @@ -# Register and Delete Runners API - -API used by Runners to register and delete themselves. - ->**Note:** -This API is intended to be used only by Runners as their own -communication channel. For the consumer API see the -[new Runners API](../runners.md). - -## Authentication - -This API uses two types of authentication: - -1. Unique Runner's token, which is the token assigned to the Runner after it - has been registered. This token can be found on the Runner's edit page (go to - **Project > Runners**, select one of the Runners listed under **Runners activated for - this project**). - -2. Using Runners' registration token. - This is a token that can be found in project's settings. - It can also be found in the **Admin > Runners** settings area. - There are two types of tokens you can pass: shared Runner registration - token or project specific registration token. - -## Register a new runner - -Used to make GitLab CI aware of available runners. - -```sh -POST /ci/api/v1/runners/register -``` - -| Attribute | Type | Required | Description | -| --------- | ------- | --------- | ----------- | -| `token` | string | yes | Runner's registration token | - -Example request: - -```sh -curl --request POST "https://gitlab.example.com/ci/api/v1/runners/register" --form "token=t0k3n" -``` - -## Delete a Runner - -Used to remove a Runner. - -```sh -DELETE /ci/api/v1/runners/delete -``` - -| Attribute | Type | Required | Description | -| --------- | ------- | --------- | ----------- | -| `token` | string | yes | Unique Runner's token | - -Example request: - -```sh -curl --request DELETE "https://gitlab.example.com/ci/api/v1/runners/delete" --form "token=t0k3n" -``` -- cgit v1.2.1 From 356c5a37d036f831c8edd91240522f9b059deb1d Mon Sep 17 00:00:00 2001 From: Shinya Maeda Date: Fri, 18 Aug 2017 15:55:04 +0000 Subject: Describe the supported version of group-level variables API in document --- doc/api/group_level_variables.md | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'doc/api') diff --git a/doc/api/group_level_variables.md b/doc/api/group_level_variables.md index e19be7b35c4..33c6da08018 100644 --- a/doc/api/group_level_variables.md +++ b/doc/api/group_level_variables.md @@ -1,5 +1,7 @@ # Group-level Variables API +> [Introduced][ce-34519] in GitLab 9.5 + ## List group variables Get list of a group's variables. @@ -123,3 +125,5 @@ DELETE /groups/:id/variables/:key ``` curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/groups/1/variables/VARIABLE_1" ``` + +[ce-34519]: https://gitlab.com/gitlab-org/gitlab-ce/issues/34519 -- cgit v1.2.1 From f5b733ebdd2c6071968e30ae0b684f82795405df Mon Sep 17 00:00:00 2001 From: Zeger-Jan van de Weg Date: Mon, 21 Aug 2017 08:38:09 +0200 Subject: Fix broken links in documentation Also, move the old linting docs to the new location. --- doc/api/README.md | 7 +------ doc/api/lint.md | 52 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 53 insertions(+), 6 deletions(-) create mode 100644 doc/api/lint.md (limited to 'doc/api') diff --git a/doc/api/README.md b/doc/api/README.md index 8acb2145f1a..266b5f018d9 100644 --- a/doc/api/README.md +++ b/doc/api/README.md @@ -55,15 +55,10 @@ following locations: - [Tags](tags.md) - [Todos](todos.md) - [Users](users.md) -- [Validate CI configuration](ci/lint.md) +- [Validate CI configuration](lint.md) - [V3 to V4](v3_to_v4.md) - [Version](version.md) -The following documentation is for the [internal CI API](ci/README.md): - -- [Builds](ci/builds.md) -- [Runners](ci/runners.md) - ## Road to GraphQL Going forward, we will start on moving to diff --git a/doc/api/lint.md b/doc/api/lint.md new file mode 100644 index 00000000000..bd5a216a99d --- /dev/null +++ b/doc/api/lint.md @@ -0,0 +1,52 @@ +# Validate the .gitlab-ci.yml (API) + +> [Introduced][ce-5953] in GitLab 8.12. + +Checks if your .gitlab-ci.yml file is valid. + +``` +POST /lint +``` + +| Attribute | Type | Required | Description | +| ---------- | ------- | -------- | -------- | +| `content` | string | yes | the .gitlab-ci.yaml content| + +```bash +curl --header "Content-Type: application/json" https://gitlab.example.com/api/v4/ci/lint --data '{"content": "{ \"image\": \"ruby:2.1\", \"services\": [\"postgres\"], \"before_script\": [\"gem install bundler\", \"bundle install\", \"bundle exec rake db:create\"], \"variables\": {\"DB_NAME\": \"postgres\"}, \"types\": [\"test\", \"deploy\", \"notify\"], \"rspec\": { \"script\": \"rake spec\", \"tags\": [\"ruby\", \"postgres\"], \"only\": [\"branches\"]}}"}' +``` + +Be sure to copy paste the exact contents of `.gitlab-ci.yml` as YAML is very picky about indentation and spaces. + +Example responses: + +* Valid content: + + ```json + { + "status": "valid", + "errors": [] + } + ``` + +* Invalid content: + + ```json + { + "status": "invalid", + "errors": [ + "variables config should be a hash of key value pairs" + ] + } + ``` + +* Without the content attribute: + + ```json + { + "error": "content is missing" + } + ``` + +[ce-5953]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5953 + -- cgit v1.2.1 From 115b598d4094a303c3941255d2bd478483f3daea Mon Sep 17 00:00:00 2001 From: Mark Fletcher Date: Thu, 24 Aug 2017 14:17:57 +0700 Subject: Document version Group Milestones API introduced --- doc/api/group_milestones.md | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'doc/api') diff --git a/doc/api/group_milestones.md b/doc/api/group_milestones.md index dbfc7529125..a96fb3124fc 100644 --- a/doc/api/group_milestones.md +++ b/doc/api/group_milestones.md @@ -1,5 +1,8 @@ # Group milestones API +> **Notes:** +> [Introduced][ce-12819] in GitLab 9.5. + ## List group milestones Returns a list of group milestones. @@ -118,3 +121,5 @@ Parameters: - `id` (required) - The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user - `milestone_id` (required) - The ID of a group milestone + +[ce-12819]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/12819 -- cgit v1.2.1 From 061472864ceaa4dc837eebcaa583f7b81d4e7e54 Mon Sep 17 00:00:00 2001 From: Nick Thomas Date: Tue, 22 Aug 2017 16:10:49 +0100 Subject: Fix group and project search for anonymous users --- doc/api/groups.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) (limited to 'doc/api') diff --git a/doc/api/groups.md b/doc/api/groups.md index 2b3d8e125c8..c2daa8bc029 100644 --- a/doc/api/groups.md +++ b/doc/api/groups.md @@ -2,7 +2,8 @@ ## List groups -Get a list of groups. (As user: my groups or all available, as admin: all groups). +Get a list of visible groups for the authenticated user. When accessed without +authentication, only public groups are returned. Parameters: @@ -43,7 +44,8 @@ You can search for groups by name or path, see below. ## List a group's projects -Get a list of projects in this group. +Get a list of projects in this group. When accessed without authentication, only +public projects are returned. ``` GET /groups/:id/projects @@ -109,7 +111,8 @@ Example response: ## Details of a group -Get all details of a group. +Get all details of a group. This endpoint can be accessed without authentication +if the group is publicly accessible. ``` GET /groups/:id -- cgit v1.2.1 From 8bd9fb4cc4f8689a23c68e1b7f893ee59907069f Mon Sep 17 00:00:00 2001 From: Robert Schilling Date: Fri, 25 Aug 2017 14:31:09 +0200 Subject: Add changelog and doc --- doc/api/README.md | 1 + 1 file changed, 1 insertion(+) (limited to 'doc/api') diff --git a/doc/api/README.md b/doc/api/README.md index 266b5f018d9..c2a08dcff07 100644 --- a/doc/api/README.md +++ b/doc/api/README.md @@ -263,6 +263,7 @@ The following table shows the possible return codes for API requests. | `404 Not Found` | A resource could not be accessed, e.g., an ID for a resource could not be found. | | `405 Method Not Allowed` | The request is not supported. | | `409 Conflict` | A conflicting resource already exists, e.g., creating a project with a name that already exists. | +| `412` | Indicates the request was denied. May happen if the `If-Unmodified-Since` header is provided when trying to delete a resource, which was modified in between. | | `422 Unprocessable` | The entity could not be processed. | | `500 Server Error` | While handling the request something went wrong server-side. | -- cgit v1.2.1 From c27b1cd394c8891285577f2843f651c7d4be469e Mon Sep 17 00:00:00 2001 From: EmilienMottet Date: Fri, 25 Aug 2017 13:17:04 +0000 Subject: fix json response --- doc/api/namespaces.md | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'doc/api') diff --git a/doc/api/namespaces.md b/doc/api/namespaces.md index 8133251dffe..5c0bebbaeb0 100644 --- a/doc/api/namespaces.md +++ b/doc/api/namespaces.md @@ -28,12 +28,14 @@ Example response: [ { "id": 1, + "name": "user1", "path": "user1", "kind": "user", "full_path": "user1" }, { "id": 2, + "name": "group1", "path": "group1", "kind": "group", "full_path": "group1", @@ -42,6 +44,7 @@ Example response: }, { "id": 3, + "name": "bar", "path": "bar", "kind": "group", "full_path": "foo/bar", @@ -77,6 +80,7 @@ Example response: [ { "id": 4, + "name": "twitter", "path": "twitter", "kind": "group", "full_path": "twitter", -- cgit v1.2.1 From 8cbc9c4ed032e7a4f73aeb86a0bec152a1c7b696 Mon Sep 17 00:00:00 2001 From: Travis Miller Date: Sat, 19 Aug 2017 12:49:39 -0500 Subject: Add time stats documentation to issue and merge request end points --- doc/api/issues.md | 56 +++++++++++++++++++++++++++++++++++++++++- doc/api/merge_requests.md | 62 +++++++++++++++++++++++++++++++++++++++++------ 2 files changed, 110 insertions(+), 8 deletions(-) (limited to 'doc/api') diff --git a/doc/api/issues.md b/doc/api/issues.md index f30ed08d0fa..14635114a31 100644 --- a/doc/api/issues.md +++ b/doc/api/issues.md @@ -101,6 +101,12 @@ Example response: "user_notes_count": 1, "due_date": "2016-07-22", "web_url": "http://example.com/example/example/issues/6", + "time_stats": { + "time_estimate": 0, + "total_time_spent": 0, + "human_time_estimate": null, + "human_total_time_spent": null + }, "confidential": false } ] @@ -198,6 +204,12 @@ Example response: "user_notes_count": 1, "due_date": null, "web_url": "http://example.com/example/example/issues/1", + "time_stats": { + "time_estimate": 0, + "total_time_spent": 0, + "human_time_estimate": null, + "human_total_time_spent": null + }, "confidential": false } ] @@ -296,6 +308,12 @@ Example response: "user_notes_count": 1, "due_date": "2016-07-22", "web_url": "http://example.com/example/example/issues/1", + "time_stats": { + "time_estimate": 0, + "total_time_spent": 0, + "human_time_estimate": null, + "human_total_time_spent": null + }, "confidential": false } ] @@ -372,6 +390,12 @@ Example response: "user_notes_count": 1, "due_date": null, "web_url": "http://example.com/example/example/issues/1", + "time_stats": { + "time_estimate": 0, + "total_time_spent": 0, + "human_time_estimate": null, + "human_total_time_spent": null + }, "confidential": false, "_links": { "self": "http://example.com/api/v4/projects/1/issues/2", @@ -440,6 +464,12 @@ Example response: "user_notes_count": 0, "due_date": null, "web_url": "http://example.com/example/example/issues/14", + "time_stats": { + "time_estimate": 0, + "total_time_spent": 0, + "human_time_estimate": null, + "human_total_time_spent": null + }, "confidential": false, "_links": { "self": "http://example.com/api/v4/projects/1/issues/2", @@ -509,6 +539,12 @@ Example response: "user_notes_count": 0, "due_date": "2016-07-22", "web_url": "http://example.com/example/example/issues/15", + "time_stats": { + "time_estimate": 0, + "total_time_spent": 0, + "human_time_estimate": null, + "human_total_time_spent": null + }, "confidential": false, "_links": { "self": "http://example.com/api/v4/projects/1/issues/2", @@ -601,6 +637,12 @@ Example response: }, "due_date": null, "web_url": "http://example.com/example/example/issues/11", + "time_stats": { + "time_estimate": 0, + "total_time_spent": 0, + "human_time_estimate": null, + "human_total_time_spent": null + }, "confidential": false, "_links": { "self": "http://example.com/api/v4/projects/1/issues/2", @@ -672,6 +714,12 @@ Example response: }, "due_date": null, "web_url": "http://example.com/example/example/issues/11", + "time_stats": { + "time_estimate": 0, + "total_time_spent": 0, + "human_time_estimate": null, + "human_total_time_spent": null + }, "confidential": false, "_links": { "self": "http://example.com/api/v4/projects/1/issues/2", @@ -1001,7 +1049,13 @@ Example response: "user_notes_count": 1, "should_remove_source_branch": null, "force_remove_source_branch": false, - "web_url": "https://gitlab.example.com/gitlab-org/gitlab-test/merge_requests/6432" + "web_url": "https://gitlab.example.com/gitlab-org/gitlab-test/merge_requests/6432", + "time_stats": { + "time_estimate": 0, + "total_time_spent": 0, + "human_time_estimate": null, + "human_total_time_spent": null + } } ] ``` diff --git a/doc/api/merge_requests.md b/doc/api/merge_requests.md index 802e5362d70..4f67aa4b9d4 100644 --- a/doc/api/merge_requests.md +++ b/doc/api/merge_requests.md @@ -92,7 +92,13 @@ Parameters: "user_notes_count": 1, "should_remove_source_branch": true, "force_remove_source_branch": false, - "web_url": "http://example.com/example/example/merge_requests/1" + "web_url": "http://example.com/example/example/merge_requests/1", + "time_stats": { + "time_estimate": 0, + "total_time_spent": 0, + "human_time_estimate": null, + "human_total_time_spent": null + } } ] ``` @@ -181,7 +187,13 @@ Parameters: "user_notes_count": 1, "should_remove_source_branch": true, "force_remove_source_branch": false, - "web_url": "http://example.com/example/example/merge_requests/1" + "web_url": "http://example.com/example/example/merge_requests/1", + "time_stats": { + "time_estimate": 0, + "total_time_spent": 0, + "human_time_estimate": null, + "human_total_time_spent": null + } } ] ``` @@ -250,7 +262,13 @@ Parameters: "user_notes_count": 1, "should_remove_source_branch": true, "force_remove_source_branch": false, - "web_url": "http://example.com/example/example/merge_requests/1" + "web_url": "http://example.com/example/example/merge_requests/1", + "time_stats": { + "time_estimate": 0, + "total_time_spent": 0, + "human_time_estimate": null, + "human_total_time_spent": null + } } ``` @@ -356,6 +374,12 @@ Parameters: "should_remove_source_branch": true, "force_remove_source_branch": false, "web_url": "http://example.com/example/example/merge_requests/1", + "time_stats": { + "time_estimate": 0, + "total_time_spent": 0, + "human_time_estimate": null, + "human_total_time_spent": null + } "changes": [ { "old_path": "VERSION", @@ -442,7 +466,13 @@ POST /projects/:id/merge_requests "user_notes_count": 0, "should_remove_source_branch": true, "force_remove_source_branch": false, - "web_url": "http://example.com/example/example/merge_requests/1" + "web_url": "http://example.com/example/example/merge_requests/1", + "time_stats": { + "time_estimate": 0, + "total_time_spent": 0, + "human_time_estimate": null, + "human_total_time_spent": null + } } ``` @@ -519,7 +549,13 @@ Must include at least one non-required attribute from above. "user_notes_count": 1, "should_remove_source_branch": true, "force_remove_source_branch": false, - "web_url": "http://example.com/example/example/merge_requests/1" + "web_url": "http://example.com/example/example/merge_requests/1", + "time_stats": { + "time_estimate": 0, + "total_time_spent": 0, + "human_time_estimate": null, + "human_total_time_spent": null + } } ``` @@ -617,7 +653,13 @@ Parameters: "user_notes_count": 1, "should_remove_source_branch": true, "force_remove_source_branch": false, - "web_url": "http://example.com/example/example/merge_requests/1" + "web_url": "http://example.com/example/example/merge_requests/1", + "time_stats": { + "time_estimate": 0, + "total_time_spent": 0, + "human_time_estimate": null, + "human_total_time_spent": null + } } ``` @@ -687,7 +729,13 @@ Parameters: "user_notes_count": 1, "should_remove_source_branch": true, "force_remove_source_branch": false, - "web_url": "http://example.com/example/example/merge_requests/1" + "web_url": "http://example.com/example/example/merge_requests/1", + "time_stats": { + "time_estimate": 0, + "total_time_spent": 0, + "human_time_estimate": null, + "human_total_time_spent": null + } } ``` -- cgit v1.2.1 From b0f982fbdf69c292ab4530c0aaaf1ab42f4e7a01 Mon Sep 17 00:00:00 2001 From: Nick Thomas Date: Mon, 21 Aug 2017 11:30:03 +0100 Subject: Add settings for minimum key strength and allowed key type MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This is an amalgamation of: * Cory Hinshaw: Initial implementation !5552 * Rémy Coutable: Updates !9350 * Nick Thomas: Resolve conflicts and add ED25519 support !13712 --- doc/api/settings.md | 19 +++++++++++++++++-- 1 file changed, 17 insertions(+), 2 deletions(-) (limited to 'doc/api') diff --git a/doc/api/settings.md b/doc/api/settings.md index 94a9f8265fb..a43e13e6217 100644 --- a/doc/api/settings.md +++ b/doc/api/settings.md @@ -48,7 +48,12 @@ Example response: "plantuml_enabled": false, "plantuml_url": null, "terminal_max_session_time": 0, - "polling_interval_multiplier": 1.0 + "polling_interval_multiplier": 1.0, + "minimum_rsa_bits": 1024, + "minimum_dsa_bits": 1024, + "minimum_ecdsa_bits": 256, + "minimum_ed25519_bits": 256, + "allowed_key_types": ["rsa", "dsa", "ecdsa", "ed25519"] } ``` @@ -88,6 +93,11 @@ PUT /application/settings | `plantuml_url` | string | yes (if `plantuml_enabled` is `true`) | The PlantUML instance URL for integration. | | `terminal_max_session_time` | integer | no | Maximum time for web terminal websocket connection (in seconds). Set to 0 for unlimited time. | | `polling_interval_multiplier` | decimal | no | Interval multiplier used by endpoints that perform polling. Set to 0 to disable polling. | +| `minimum_rsa_bits` | integer | no | The minimum allowed bit length of an uploaded RSA key. Default is `1024`. +| `minimum_dsa_bits` | integer | no | The minimum allowed bit length of an uploaded DSA key. Default is `1024`. +| `minimum_ecdsa_bits` | integer | no | The minimum allowed curve size (in bits) of an uploaded ECDSA key. Default is `256`. +| `minimum_ed25519_bits` | integer | no | The minimum allowed curve size (in bits) of an uploaded ED25519 key. Default is `256`. +| `allowed_key_types` | array of strings | no | Array of SSH key types accepted by the application. Allowed values are: `rsa`, `dsa`, `ecdsa`, and `ed25519`. Default is `["rsa", "dsa", "ecdsa", "ed25519"]`. ```bash curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/application/settings?signup_enabled=false&default_project_visibility=internal @@ -125,6 +135,11 @@ Example response: "plantuml_enabled": false, "plantuml_url": null, "terminal_max_session_time": 0, - "polling_interval_multiplier": 1.0 + "polling_interval_multiplier": 1.0, + "minimum_rsa_bits": 1024, + "minimum_dsa_bits": 1024, + "minimum_ecdsa_bits": 256, + "minimum_ed25519_bits": 256, + "allowed_key_types": ["rsa", "dsa", "ecdsa", "ed25519"] } ``` -- cgit v1.2.1 From 6847060266792471c9c14518a5106e0f622cd6c5 Mon Sep 17 00:00:00 2001 From: Nick Thomas Date: Fri, 25 Aug 2017 14:08:48 +0100 Subject: Rework the permissions model for SSH key restrictions `allowed_key_types` is removed and the `minimum__bits` fields are renamed to `_key_restriction`. A special sentinel value (`-1`) signifies that the key type is disabled. This also feeds through to the UI - checkboxes per key type are out, inline selection of "forbidden" and "allowed" (i.e., no restrictions) are in. As with the previous model, unknown key types are disallowed, even if the underlying ssh daemon happens to support them. The defaults have also been changed from the lowest known bit size to "no restriction". So if someone does happen to have a 768-bit RSA key, it will continue to work on upgrade, at least until the administrator restricts them. --- doc/api/settings.md | 27 ++++++++++++--------------- 1 file changed, 12 insertions(+), 15 deletions(-) (limited to 'doc/api') diff --git a/doc/api/settings.md b/doc/api/settings.md index a43e13e6217..b78f1252108 100644 --- a/doc/api/settings.md +++ b/doc/api/settings.md @@ -49,11 +49,10 @@ Example response: "plantuml_url": null, "terminal_max_session_time": 0, "polling_interval_multiplier": 1.0, - "minimum_rsa_bits": 1024, - "minimum_dsa_bits": 1024, - "minimum_ecdsa_bits": 256, - "minimum_ed25519_bits": 256, - "allowed_key_types": ["rsa", "dsa", "ecdsa", "ed25519"] + "rsa_key_restriction": 0, + "dsa_key_restriction": 0, + "ecdsa_key_restriction": 0, + "ed25519_key_restriction": 0, } ``` @@ -93,11 +92,10 @@ PUT /application/settings | `plantuml_url` | string | yes (if `plantuml_enabled` is `true`) | The PlantUML instance URL for integration. | | `terminal_max_session_time` | integer | no | Maximum time for web terminal websocket connection (in seconds). Set to 0 for unlimited time. | | `polling_interval_multiplier` | decimal | no | Interval multiplier used by endpoints that perform polling. Set to 0 to disable polling. | -| `minimum_rsa_bits` | integer | no | The minimum allowed bit length of an uploaded RSA key. Default is `1024`. -| `minimum_dsa_bits` | integer | no | The minimum allowed bit length of an uploaded DSA key. Default is `1024`. -| `minimum_ecdsa_bits` | integer | no | The minimum allowed curve size (in bits) of an uploaded ECDSA key. Default is `256`. -| `minimum_ed25519_bits` | integer | no | The minimum allowed curve size (in bits) of an uploaded ED25519 key. Default is `256`. -| `allowed_key_types` | array of strings | no | Array of SSH key types accepted by the application. Allowed values are: `rsa`, `dsa`, `ecdsa`, and `ed25519`. Default is `["rsa", "dsa", "ecdsa", "ed25519"]`. +| `rsa_key_restriction` | integer | no | The minimum allowed bit length of an uploaded RSA key. Default is `0` (no restriction). `-1` disables RSA keys. +| `dsa_key_restriction` | integer | no | The minimum allowed bit length of an uploaded DSA key. Default is `0` (no restriction). `-1` disables DSA keys. +| `ecdsa_key_restriction` | integer | no | The minimum allowed curve size (in bits) of an uploaded ECDSA key. Default is `0` (no restriction). `-1` disables ECDSA keys. +| `ed25519_key_restriction` | integer | no | The minimum allowed curve size (in bits) of an uploaded ED25519 key. Default is `0` (no restriction). `-1` disables ED25519 keys. ```bash curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/application/settings?signup_enabled=false&default_project_visibility=internal @@ -136,10 +134,9 @@ Example response: "plantuml_url": null, "terminal_max_session_time": 0, "polling_interval_multiplier": 1.0, - "minimum_rsa_bits": 1024, - "minimum_dsa_bits": 1024, - "minimum_ecdsa_bits": 256, - "minimum_ed25519_bits": 256, - "allowed_key_types": ["rsa", "dsa", "ecdsa", "ed25519"] + "rsa_key_restriction": 0, + "dsa_key_restriction": 0, + "ecdsa_key_restriction": 0, + "ed25519_key_restriction": 0, } ``` -- cgit v1.2.1 From 03af5e2e8d9f6ca2c438fd8243ab7f6aa86462c4 Mon Sep 17 00:00:00 2001 From: Mark Fletcher Date: Sat, 2 Sep 2017 13:52:12 +0800 Subject: Add to_project_id parameter to Move Issue via API example --- doc/api/issues.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/api') diff --git a/doc/api/issues.md b/doc/api/issues.md index f30ed08d0fa..5da715ee1b5 100644 --- a/doc/api/issues.md +++ b/doc/api/issues.md @@ -558,7 +558,7 @@ POST /projects/:id/issues/:issue_iid/move | `to_project_id` | integer | yes | The ID of the new project | ```bash -curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/4/issues/85/move +curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --data '{"to_project_id": 5}' https://gitlab.example.com/api/v4/projects/4/issues/85/move ``` Example response: -- cgit v1.2.1 From d7cf49bff0074b03380b57ae3c790f63ee821e02 Mon Sep 17 00:00:00 2001 From: "Vitaliy @blackst0ne Klachkov" Date: Sun, 3 Sep 2017 13:00:32 +1100 Subject: Fix typo in the API Deploy Keys documentation page --- doc/api/deploy_keys.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/api') diff --git a/doc/api/deploy_keys.md b/doc/api/deploy_keys.md index 4fa800ecb9c..273d5a56b6f 100644 --- a/doc/api/deploy_keys.md +++ b/doc/api/deploy_keys.md @@ -106,7 +106,7 @@ Example response: Creates a new deploy key for a project. If the deploy key already exists in another project, it will be joined to current -project only if original one was is accessible by the same user. +project only if original one is accessible by the same user. ``` POST /projects/:id/deploy_keys -- cgit v1.2.1 From 6f19fc1147a60f279db35428993ac532841195ad Mon Sep 17 00:00:00 2001 From: Shinya Maeda Date: Thu, 24 Aug 2017 01:28:57 +0900 Subject: Add API support --- doc/api/runners.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) (limited to 'doc/api') diff --git a/doc/api/runners.md b/doc/api/runners.md index 16d362a3530..dcca30dbfa7 100644 --- a/doc/api/runners.md +++ b/doc/api/runners.md @@ -138,7 +138,8 @@ Example response: "ruby", "mysql" ], - "version": null + "version": null, + "access_level": 0 } ``` @@ -156,6 +157,9 @@ PUT /runners/:id | `description` | string | no | The description of a runner | | `active` | boolean | no | The state of a runner; can be set to `true` or `false` | | `tag_list` | array | no | The list of tags for a runner; put array of tags, that should be finally assigned to a runner | +| `run_untagged` | boolean | no | Flag indicating the runner can execute untagged jobs | +| `locked` | boolean | no | Flag indicating the runner is locked | +| `access_level` | integer | no | The access_level of the runner; `unprotected`: 0, `protected`: 1 | ``` curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/runners/6" --form "description=test-1-20150125-test" --form "tag_list=ruby,mysql,tag1,tag2" @@ -190,7 +194,8 @@ Example response: "tag1", "tag2" ], - "version": null + "version": null, + "access_level": 0 } ``` -- cgit v1.2.1 From 1024718e9fddbb0d61d3f64f44303964641fcdd8 Mon Sep 17 00:00:00 2001 From: Shinya Maeda Date: Tue, 29 Aug 2017 15:56:03 +0900 Subject: Refactor access_level to not_protected and ref_protected --- doc/api/runners.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/api') diff --git a/doc/api/runners.md b/doc/api/runners.md index dcca30dbfa7..df458af77bb 100644 --- a/doc/api/runners.md +++ b/doc/api/runners.md @@ -159,7 +159,7 @@ PUT /runners/:id | `tag_list` | array | no | The list of tags for a runner; put array of tags, that should be finally assigned to a runner | | `run_untagged` | boolean | no | Flag indicating the runner can execute untagged jobs | | `locked` | boolean | no | Flag indicating the runner is locked | -| `access_level` | integer | no | The access_level of the runner; `unprotected`: 0, `protected`: 1 | +| `access_level` | integer | no | The access_level of the runner; `not_protected`: 0, `ref_protected`: 1 | ``` curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/runners/6" --form "description=test-1-20150125-test" --form "tag_list=ruby,mysql,tag1,tag2" -- cgit v1.2.1 From 13b9b5f11a556b2841aabbf46516d1acab79aa0d Mon Sep 17 00:00:00 2001 From: Shinya Maeda Date: Tue, 29 Aug 2017 16:09:30 +0900 Subject: Improve API arguments as String --- doc/api/runners.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'doc/api') diff --git a/doc/api/runners.md b/doc/api/runners.md index df458af77bb..8146a7e0647 100644 --- a/doc/api/runners.md +++ b/doc/api/runners.md @@ -139,7 +139,7 @@ Example response: "mysql" ], "version": null, - "access_level": 0 + "access_level": "ref_protected" } ``` @@ -159,7 +159,7 @@ PUT /runners/:id | `tag_list` | array | no | The list of tags for a runner; put array of tags, that should be finally assigned to a runner | | `run_untagged` | boolean | no | Flag indicating the runner can execute untagged jobs | | `locked` | boolean | no | Flag indicating the runner is locked | -| `access_level` | integer | no | The access_level of the runner; `not_protected`: 0, `ref_protected`: 1 | +| `access_level` | integer | no | The access_level of the runner; `not_protected` or `ref_protected` | ``` curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/runners/6" --form "description=test-1-20150125-test" --form "tag_list=ruby,mysql,tag1,tag2" @@ -195,7 +195,7 @@ Example response: "tag2" ], "version": null, - "access_level": 0 + "access_level": "ref_protected" } ``` -- cgit v1.2.1 From a2cde2847c68e8061f6f40f106502fa164be7b02 Mon Sep 17 00:00:00 2001 From: Shinya Maeda Date: Tue, 29 Aug 2017 18:57:53 +0900 Subject: Fix runner api doc --- doc/api/runners.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/api') diff --git a/doc/api/runners.md b/doc/api/runners.md index 8146a7e0647..6304a496f94 100644 --- a/doc/api/runners.md +++ b/doc/api/runners.md @@ -159,7 +159,7 @@ PUT /runners/:id | `tag_list` | array | no | The list of tags for a runner; put array of tags, that should be finally assigned to a runner | | `run_untagged` | boolean | no | Flag indicating the runner can execute untagged jobs | | `locked` | boolean | no | Flag indicating the runner is locked | -| `access_level` | integer | no | The access_level of the runner; `not_protected` or `ref_protected` | +| `access_level` | string | no | The access_level of the runner; `not_protected` or `ref_protected` | ``` curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/runners/6" --form "description=test-1-20150125-test" --form "tag_list=ruby,mysql,tag1,tag2" -- cgit v1.2.1 From 8ca5c333fd5170a900c7fa28b6bfcbe1a8bc6477 Mon Sep 17 00:00:00 2001 From: Shinya Maeda Date: Fri, 18 Aug 2017 17:25:35 +0900 Subject: Extend API: Pipeline Schedule Variable --- doc/api/pipeline_schedules.md | 161 +++++++++++++++++++++++++++++++++++++++++- 1 file changed, 160 insertions(+), 1 deletion(-) (limited to 'doc/api') diff --git a/doc/api/pipeline_schedules.md b/doc/api/pipeline_schedules.md index 433654c18cc..d2169b0377d 100644 --- a/doc/api/pipeline_schedules.md +++ b/doc/api/pipeline_schedules.md @@ -84,7 +84,13 @@ curl --header "PRIVATE-TOKEN: k5ESFgWY2Qf5xEvDcFxZ" "https://gitlab.example.com/ "state": "active", "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", "web_url": "https://gitlab.example.com/root" - } + }, + "variables": [ + { + "key": "TEST_VARIABLE_1", + "value": "TEST_1" + } + ] } ``` @@ -271,3 +277,156 @@ curl --request DELETE --header "PRIVATE-TOKEN: k5ESFgWY2Qf5xEvDcFxZ" "https://gi } } ``` + +## Create a new pipeline schedule variable + +Create a new variable of a pipeline schedule. + +``` +POST /projects/:id/pipeline_schedules/:pipeline_schedule_id/variables +``` + +| Attribute | Type | required | Description | +|---------------|---------|----------|--------------------------| +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | +| `pipeline_schedule_id` | integer | yes | The pipeline schedule id | +| `key` | string | yes | The `key` of a variable; must have no more than 255 characters; only `A-Z`, `a-z`, `0-9`, and `_` are allowed | +| `value` | string | yes | The `value` of a variable | + +```sh +curl --request POST --header "PRIVATE-TOKEN: k5ESFgWY2Qf5xEvDcFxZ" --form "key=NEW_VARIABLE" --form "value=new value" "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules/13/variables" +``` + +```json +{ + "id": 13, + "description": "Test schedule pipeline", + "ref": "master", + "cron": "* * * * *", + "cron_timezone": "Asia/Tokyo", + "next_run_at": "2017-05-19T13:41:00.000Z", + "active": true, + "created_at": "2017-05-19T13:31:08.849Z", + "updated_at": "2017-05-19T13:40:17.727Z", + "last_pipeline": { + "id": 332, + "sha": "0e788619d0b5ec17388dffb973ecd505946156db", + "ref": "master", + "status": "pending" + }, + "owner": { + "name": "Administrator", + "username": "root", + "id": 1, + "state": "active", + "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", + "web_url": "https://gitlab.example.com/root" + }, + "variables": [ + { + "key": "NEW_VARIABLE", + "value": "new value" + } + ] +} +``` + +## Edit a pipeline schedule variable + +Updates the variable of a pipeline schedule. + +``` +PUT /projects/:id/pipeline_schedules/:pipeline_schedule_id/variables/:key +``` + +| Attribute | Type | required | Description | +|---------------|---------|----------|--------------------------| +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | +| `pipeline_schedule_id` | integer | yes | The pipeline schedule id | +| `key` | string | yes | The `key` of a variable | +| `value` | string | yes | The `value` of a variable | + +```sh +curl --request PUT --header "PRIVATE-TOKEN: k5ESFgWY2Qf5xEvDcFxZ" --form "value=updated value" "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules/13/variables/NEW_VARIABLE" +``` + +```json +{ + "id": 13, + "description": "Test schedule pipeline", + "ref": "master", + "cron": "* * * * *", + "cron_timezone": "Asia/Tokyo", + "next_run_at": "2017-05-19T13:41:00.000Z", + "active": true, + "created_at": "2017-05-19T13:31:08.849Z", + "updated_at": "2017-05-19T13:40:17.727Z", + "last_pipeline": { + "id": 332, + "sha": "0e788619d0b5ec17388dffb973ecd505946156db", + "ref": "master", + "status": "pending" + }, + "owner": { + "name": "Administrator", + "username": "root", + "id": 1, + "state": "active", + "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", + "web_url": "https://gitlab.example.com/root" + }, + "variables": [ + { + "key": "NEW_VARIABLE", + "value": "updated value" + } + ] +} +``` + +## Delete a pipeline schedule variable + +Delete the variable of a pipeline schedule. + +``` +DELETE /projects/:id/pipeline_schedules/:pipeline_schedule_id/variables/:key +``` + +| Attribute | Type | required | Description | +|----------------|---------|----------|--------------------------| +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | +| `pipeline_schedule_id` | integer | yes | The pipeline schedule id | +| `key` | string | yes | The `key` of a variable | + +```sh +curl --request DELETE --header "PRIVATE-TOKEN: k5ESFgWY2Qf5xEvDcFxZ" "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules/13/variables/NEW_VARIABLE" +``` + +```json +{ + "id": 13, + "description": "Test schedule pipeline", + "ref": "master", + "cron": "* * * * *", + "cron_timezone": "Asia/Tokyo", + "next_run_at": "2017-05-19T13:41:00.000Z", + "active": true, + "created_at": "2017-05-19T13:31:08.849Z", + "updated_at": "2017-05-19T13:40:17.727Z", + "last_pipeline": { + "id": 332, + "sha": "0e788619d0b5ec17388dffb973ecd505946156db", + "ref": "master", + "status": "pending" + }, + "owner": { + "name": "Administrator", + "username": "root", + "id": 1, + "state": "active", + "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", + "web_url": "https://gitlab.example.com/root" + }, + "variables": [] +} +``` -- cgit v1.2.1 From 683ba258cb95d5596b545d94420a9b6262f5d45b Mon Sep 17 00:00:00 2001 From: Shinya Maeda Date: Fri, 18 Aug 2017 17:46:14 +0900 Subject: Fix doc --- doc/api/pipeline_schedules.md | 95 +++++-------------------------------------- 1 file changed, 11 insertions(+), 84 deletions(-) (limited to 'doc/api') diff --git a/doc/api/pipeline_schedules.md b/doc/api/pipeline_schedules.md index d2169b0377d..bfa6fb731eb 100644 --- a/doc/api/pipeline_schedules.md +++ b/doc/api/pipeline_schedules.md @@ -278,6 +278,10 @@ curl --request DELETE --header "PRIVATE-TOKEN: k5ESFgWY2Qf5xEvDcFxZ" "https://gi } ``` +## Pipeline schedule variable + +> [Introduced][ce-34518] in GitLab 10.0. + ## Create a new pipeline schedule variable Create a new variable of a pipeline schedule. @@ -299,35 +303,8 @@ curl --request POST --header "PRIVATE-TOKEN: k5ESFgWY2Qf5xEvDcFxZ" --form "key=N ```json { - "id": 13, - "description": "Test schedule pipeline", - "ref": "master", - "cron": "* * * * *", - "cron_timezone": "Asia/Tokyo", - "next_run_at": "2017-05-19T13:41:00.000Z", - "active": true, - "created_at": "2017-05-19T13:31:08.849Z", - "updated_at": "2017-05-19T13:40:17.727Z", - "last_pipeline": { - "id": 332, - "sha": "0e788619d0b5ec17388dffb973ecd505946156db", - "ref": "master", - "status": "pending" - }, - "owner": { - "name": "Administrator", - "username": "root", - "id": 1, - "state": "active", - "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", - "web_url": "https://gitlab.example.com/root" - }, - "variables": [ - { - "key": "NEW_VARIABLE", - "value": "new value" - } - ] + "key": "NEW_VARIABLE", + "value": "new value" } ``` @@ -352,35 +329,8 @@ curl --request PUT --header "PRIVATE-TOKEN: k5ESFgWY2Qf5xEvDcFxZ" --form "value= ```json { - "id": 13, - "description": "Test schedule pipeline", - "ref": "master", - "cron": "* * * * *", - "cron_timezone": "Asia/Tokyo", - "next_run_at": "2017-05-19T13:41:00.000Z", - "active": true, - "created_at": "2017-05-19T13:31:08.849Z", - "updated_at": "2017-05-19T13:40:17.727Z", - "last_pipeline": { - "id": 332, - "sha": "0e788619d0b5ec17388dffb973ecd505946156db", - "ref": "master", - "status": "pending" - }, - "owner": { - "name": "Administrator", - "username": "root", - "id": 1, - "state": "active", - "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", - "web_url": "https://gitlab.example.com/root" - }, - "variables": [ - { - "key": "NEW_VARIABLE", - "value": "updated value" - } - ] + "key": "NEW_VARIABLE", + "value": "updated value" } ``` @@ -403,30 +353,7 @@ curl --request DELETE --header "PRIVATE-TOKEN: k5ESFgWY2Qf5xEvDcFxZ" "https://gi ``` ```json -{ - "id": 13, - "description": "Test schedule pipeline", - "ref": "master", - "cron": "* * * * *", - "cron_timezone": "Asia/Tokyo", - "next_run_at": "2017-05-19T13:41:00.000Z", - "active": true, - "created_at": "2017-05-19T13:31:08.849Z", - "updated_at": "2017-05-19T13:40:17.727Z", - "last_pipeline": { - "id": 332, - "sha": "0e788619d0b5ec17388dffb973ecd505946156db", - "ref": "master", - "status": "pending" - }, - "owner": { - "name": "Administrator", - "username": "root", - "id": 1, - "state": "active", - "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", - "web_url": "https://gitlab.example.com/root" - }, - "variables": [] -} +// Empty ``` + +[ce-34518]: https://gitlab.com/gitlab-org/gitlab-ce/issues/34518 \ No newline at end of file -- cgit v1.2.1 From 362f2226a5febb7a3a82e86f4a83e87a870d67b3 Mon Sep 17 00:00:00 2001 From: Shinya Maeda Date: Thu, 24 Aug 2017 21:51:46 +0900 Subject: Improve by zj nice catches --- doc/api/pipeline_schedules.md | 39 +++++++++++++++++++++------------------ 1 file changed, 21 insertions(+), 18 deletions(-) (limited to 'doc/api') diff --git a/doc/api/pipeline_schedules.md b/doc/api/pipeline_schedules.md index bfa6fb731eb..c28f48e5fc6 100644 --- a/doc/api/pipeline_schedules.md +++ b/doc/api/pipeline_schedules.md @@ -290,12 +290,12 @@ Create a new variable of a pipeline schedule. POST /projects/:id/pipeline_schedules/:pipeline_schedule_id/variables ``` -| Attribute | Type | required | Description | -|---------------|---------|----------|--------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | -| `pipeline_schedule_id` | integer | yes | The pipeline schedule id | -| `key` | string | yes | The `key` of a variable; must have no more than 255 characters; only `A-Z`, `a-z`, `0-9`, and `_` are allowed | -| `value` | string | yes | The `value` of a variable | +| Attribute | Type | required | Description | +|------------------------|----------------|----------|--------------------------| +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | +| `pipeline_schedule_id` | integer | yes | The pipeline schedule id | +| `key` | string | yes | The `key` of a variable; must have no more than 255 characters; only `A-Z`, `a-z`, `0-9`, and `_` are allowed | +| `value` | string | yes | The `value` of a variable | ```sh curl --request POST --header "PRIVATE-TOKEN: k5ESFgWY2Qf5xEvDcFxZ" --form "key=NEW_VARIABLE" --form "value=new value" "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules/13/variables" @@ -316,12 +316,12 @@ Updates the variable of a pipeline schedule. PUT /projects/:id/pipeline_schedules/:pipeline_schedule_id/variables/:key ``` -| Attribute | Type | required | Description | -|---------------|---------|----------|--------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | -| `pipeline_schedule_id` | integer | yes | The pipeline schedule id | -| `key` | string | yes | The `key` of a variable | -| `value` | string | yes | The `value` of a variable | +| Attribute | Type | required | Description | +|------------------------|----------------|----------|--------------------------| +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | +| `pipeline_schedule_id` | integer | yes | The pipeline schedule id | +| `key` | string | yes | The `key` of a variable | +| `value` | string | yes | The `value` of a variable | ```sh curl --request PUT --header "PRIVATE-TOKEN: k5ESFgWY2Qf5xEvDcFxZ" --form "value=updated value" "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules/13/variables/NEW_VARIABLE" @@ -342,18 +342,21 @@ Delete the variable of a pipeline schedule. DELETE /projects/:id/pipeline_schedules/:pipeline_schedule_id/variables/:key ``` -| Attribute | Type | required | Description | -|----------------|---------|----------|--------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | -| `pipeline_schedule_id` | integer | yes | The pipeline schedule id | -| `key` | string | yes | The `key` of a variable | +| Attribute | Type | required | Description | +|------------------------|----------------|----------|--------------------------| +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | +| `pipeline_schedule_id` | integer | yes | The pipeline schedule id | +| `key` | string | yes | The `key` of a variable | ```sh curl --request DELETE --header "PRIVATE-TOKEN: k5ESFgWY2Qf5xEvDcFxZ" "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules/13/variables/NEW_VARIABLE" ``` ```json -// Empty +{ + "key": "NEW_VARIABLE", + "value": "updated value" +} ``` [ce-34518]: https://gitlab.com/gitlab-org/gitlab-ce/issues/34518 \ No newline at end of file -- cgit v1.2.1 From cf9c54bd312dcb7b4b7f0602e83013d8d32a9413 Mon Sep 17 00:00:00 2001 From: Hiroyuki Sato Date: Sun, 3 Sep 2017 16:34:50 +0900 Subject: Add my_reaction_emoji param to /issues API --- doc/api/issues.md | 94 +++++++++++++++++++++++++++++-------------------------- 1 file changed, 50 insertions(+), 44 deletions(-) (limited to 'doc/api') diff --git a/doc/api/issues.md b/doc/api/issues.md index 765246142c1..f8f9db484e2 100644 --- a/doc/api/issues.md +++ b/doc/api/issues.md @@ -30,20 +30,22 @@ GET /issues?milestone=1.0.0&state=opened GET /issues?iids[]=42&iids[]=43 GET /issues?author_id=5 GET /issues?assignee_id=5 -``` - -| Attribute | Type | Required | Description | -|-------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------------------| -| `state` | string | no | Return all issues or just those that are `opened` or `closed` | -| `labels` | string | no | Comma-separated list of label names, issues must have all labels to be returned. `No+Label` lists all issues with no labels | -| `milestone` | string | no | The milestone title | -| `scope` | string | no | Return issues for the given scope: `created-by-me`, `assigned-to-me` or `all`. Defaults to `created-by-me` _([Introduced][ce-13004] in GitLab 9.5)_ | -| `author_id` | integer | no | Return issues created by the given user `id`. Combine with `scope=all` or `scope=assigned-to-me`. _([Introduced][ce-13004] in GitLab 9.5)_ | -| `assignee_id` | integer | no | Return issues assigned to the given user `id` _([Introduced][ce-13004] in GitLab 9.5)_ | -| `iids[]` | Array[integer] | no | Return only the issues having the given `iid` | -| `order_by` | string | no | Return issues ordered by `created_at` or `updated_at` fields. Default is `created_at` | -| `sort` | string | no | Return issues sorted in `asc` or `desc` order. Default is `desc` | -| `search` | string | no | Search issues against their `title` and `description` | +GET /issues?my_reaction_emoji=star +``` + +| Attribute | Type | Required | Description | +| ------------------- | ---------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | +| `state` | string | no | Return all issues or just those that are `opened` or `closed` | +| `labels` | string | no | Comma-separated list of label names, issues must have all labels to be returned. `No+Label` lists all issues with no labels | +| `milestone` | string | no | The milestone title | +| `scope` | string | no | Return issues for the given scope: `created-by-me`, `assigned-to-me` or `all`. Defaults to `created-by-me` _([Introduced][ce-13004] in GitLab 9.5)_ | +| `author_id` | integer | no | Return issues created by the given user `id`. Combine with `scope=all` or `scope=assigned-to-me`. _([Introduced][ce-13004] in GitLab 9.5)_ | +| `assignee_id` | integer | no | Return issues assigned to the given user `id` _([Introduced][ce-13004] in GitLab 9.5)_ | +| `my_reaction_emoji` | string | no | Return issues reacted by the authenticated user by the given emoji ` _([Introduced][ce-14016] in GitLab 10.0)_ | +| `iids[]` | Array[integer] | no | Return only the issues having the given `iid` | +| `order_by` | string | no | Return issues ordered by `created_at` or `updated_at` fields. Default is `created_at` | +| `sort` | string | no | Return issues sorted in `asc` or `desc` order. Default is `desc` | +| `search` | string | no | Search issues against their `title` and `description` | ```bash curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/issues @@ -131,21 +133,23 @@ GET /groups/:id/issues?iids[]=42&iids[]=43 GET /groups/:id/issues?search=issue+title+or+description GET /groups/:id/issues?author_id=5 GET /groups/:id/issues?assignee_id=5 +GET /groups/:id/issues?my_reaction_emoji=star ``` -| Attribute | Type | Required | Description | -|-------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | -| `state` | string | no | Return all issues or just those that are `opened` or `closed` | -| `labels` | string | no | Comma-separated list of label names, issues must have all labels to be returned. `No+Label` lists all issues with no labels | -| `iids[]` | Array[integer] | no | Return only the issues having the given `iid` | -| `milestone` | string | no | The milestone title | -| `scope` | string | no | Return issues for the given scope: `created-by-me`, `assigned-to-me` or `all` _([Introduced][ce-13004] in GitLab 9.5)_ | -| `author_id` | integer | no | Return issues created by the given user `id` _([Introduced][ce-13004] in GitLab 9.5)_ | -| `assignee_id` | integer | no | Return issues assigned to the given user `id` _([Introduced][ce-13004] in GitLab 9.5)_ | -| `order_by` | string | no | Return issues ordered by `created_at` or `updated_at` fields. Default is `created_at` | -| `sort` | string | no | Return issues sorted in `asc` or `desc` order. Default is `desc` | -| `search` | string | no | Search group issues against their `title` and `description` | +| Attribute | Type | Required | Description | +| ------------------- | ---------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `state` | string | no | Return all issues or just those that are `opened` or `closed` | +| `labels` | string | no | Comma-separated list of label names, issues must have all labels to be returned. `No+Label` lists all issues with no labels | +| `iids[]` | Array[integer] | no | Return only the issues having the given `iid` | +| `milestone` | string | no | The milestone title | +| `scope` | string | no | Return issues for the given scope: `created-by-me`, `assigned-to-me` or `all` _([Introduced][ce-13004] in GitLab 9.5)_ | +| `author_id` | integer | no | Return issues created by the given user `id` _([Introduced][ce-13004] in GitLab 9.5)_ | +| `assignee_id` | integer | no | Return issues assigned to the given user `id` _([Introduced][ce-13004] in GitLab 9.5)_ | +| `my_reaction_emoji` | string | no | Return issues reacted by the authenticated user by the given emoji ` _([Introduced][ce-14016] in GitLab 10.0)_ | +| `order_by` | string | no | Return issues ordered by `created_at` or `updated_at` fields. Default is `created_at` | +| `sort` | string | no | Return issues sorted in `asc` or `desc` order. Default is `desc` | +| `search` | string | no | Search group issues against their `title` and `description` | ```bash @@ -234,23 +238,25 @@ GET /projects/:id/issues?iids[]=42&iids[]=43 GET /projects/:id/issues?search=issue+title+or+description GET /projects/:id/issues?author_id=5 GET /projects/:id/issues?assignee_id=5 -``` - -| Attribute | Type | Required | Description | -|-------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | -| `iids[]` | Array[integer] | no | Return only the milestone having the given `iid` | -| `state` | string | no | Return all issues or just those that are `opened` or `closed` | -| `labels` | string | no | Comma-separated list of label names, issues must have all labels to be returned. `No+Label` lists all issues with no labels | -| `milestone` | string | no | The milestone title | -| `scope` | string | no | Return issues for the given scope: `created-by-me`, `assigned-to-me` or `all` _([Introduced][ce-13004] in GitLab 9.5)_ | -| `author_id` | integer | no | Return issues created by the given user `id` _([Introduced][ce-13004] in GitLab 9.5)_ | -| `assignee_id` | integer | no | Return issues assigned to the given user `id` _([Introduced][ce-13004] in GitLab 9.5)_ | -| `order_by` | string | no | Return issues ordered by `created_at` or `updated_at` fields. Default is `created_at` | -| `sort` | string | no | Return issues sorted in `asc` or `desc` order. Default is `desc` | -| `search` | string | no | Search project issues against their `title` and `description` | -| `created_after` | datetime | no | Return issues created after the given time (inclusive) | -| `created_before` | datetime | no | Return issues created before the given time (inclusive) | +GET /projects/:id/issues?my_reaction_emoji=star +``` + +| Attribute | Type | Required | Description | +| ------------------- | ---------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | +| `iids[]` | Array[integer] | no | Return only the milestone having the given `iid` | +| `state` | string | no | Return all issues or just those that are `opened` or `closed` | +| `labels` | string | no | Comma-separated list of label names, issues must have all labels to be returned. `No+Label` lists all issues with no labels | +| `milestone` | string | no | The milestone title | +| `scope` | string | no | Return issues for the given scope: `created-by-me`, `assigned-to-me` or `all` _([Introduced][ce-13004] in GitLab 9.5)_ | +| `author_id` | integer | no | Return issues created by the given user `id` _([Introduced][ce-13004] in GitLab 9.5)_ | +| `assignee_id` | integer | no | Return issues assigned to the given user `id` _([Introduced][ce-13004] in GitLab 9.5)_ | +| `my_reaction_emoji` | string | no | Return issues reacted by the authenticated user by the given emoji ` _([Introduced][ce-14016] in GitLab 10.0)_ | +| `order_by` | string | no | Return issues ordered by `created_at` or `updated_at` fields. Default is `created_at` | +| `sort` | string | no | Return issues sorted in `asc` or `desc` order. Default is `desc` | +| `search` | string | no | Search project issues against their `title` and `description` | +| `created_after` | datetime | no | Return issues created after the given time (inclusive) | +| `created_before` | datetime | no | Return issues created before the given time (inclusive) | ```bash curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/4/issues -- cgit v1.2.1 From 7e42711659d514be77119698d2611830fb83090d Mon Sep 17 00:00:00 2001 From: Hiroyuki Sato Date: Mon, 4 Sep 2017 10:43:14 +0900 Subject: Add my_reaction_emoji param to /merge_requests API --- doc/api/merge_requests.md | 30 +++++++++++++++++------------- 1 file changed, 17 insertions(+), 13 deletions(-) (limited to 'doc/api') diff --git a/doc/api/merge_requests.md b/doc/api/merge_requests.md index 4f67aa4b9d4..a0b31d3633c 100644 --- a/doc/api/merge_requests.md +++ b/doc/api/merge_requests.md @@ -22,24 +22,26 @@ GET /merge_requests?state=all GET /merge_requests?milestone=release GET /merge_requests?labels=bug,reproduced GET /merge_requests?author_id=5 +GET /merge_requests?my_reaction_emoji=star GET /merge_requests?scope=assigned-to-me ``` Parameters: -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `state` | string | no | Return all merge requests or just those that are `opened`, `closed`, or `merged`| -| `order_by`| string | no | Return requests ordered by `created_at` or `updated_at` fields. Default is `created_at` | -| `sort` | string | no | Return requests sorted in `asc` or `desc` order. Default is `desc` | -| `milestone` | string | no | Return merge requests for a specific milestone | -| `view` | string | no | If `simple`, returns the `iid`, URL, title, description, and basic state of merge request | -| `labels` | string | no | Return merge requests matching a comma separated list of labels | -| `created_after` | datetime | no | Return merge requests created after the given time (inclusive) | -| `created_before` | datetime | no | Return merge requests created before the given time (inclusive) | -| `scope` | string | no | Return merge requests for the given scope: `created-by-me`, `assigned-to-me` or `all`. Defaults to `created-by-me` | -| `author_id` | integer | no | Returns merge requests created by the given user `id`. Combine with `scope=all` or `scope=assigned-to-me` | -| `assignee_id` | integer | no | Returns merge requests assigned to the given user `id` | +| Attribute | Type | Required | Description | +| ------------------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------- | +| `state` | string | no | Return all merge requests or just those that are `opened`, `closed`, or `merged` | +| `order_by` | string | no | Return requests ordered by `created_at` or `updated_at` fields. Default is `created_at` | +| `sort` | string | no | Return requests sorted in `asc` or `desc` order. Default is `desc` | +| `milestone` | string | no | Return merge requests for a specific milestone | +| `view` | string | no | If `simple`, returns the `iid`, URL, title, description, and basic state of merge request | +| `labels` | string | no | Return merge requests matching a comma separated list of labels | +| `created_after` | datetime | no | Return merge requests created after the given time (inclusive) | +| `created_before` | datetime | no | Return merge requests created before the given time (inclusive) | +| `scope` | string | no | Return merge requests for the given scope: `created-by-me`, `assigned-to-me` or `all`. Defaults to `created-by-me` | +| `author_id` | integer | no | Returns merge requests created by the given user `id`. Combine with `scope=all` or `scope=assigned-to-me` | +| `assignee_id` | integer | no | Returns merge requests assigned to the given user `id` | +| `my_reaction_emoji` | string | no | Return merge requests reacted by the authenticated user by the given emoji ` _([Introduced][ce-14016] in GitLab 10.0)_ | ```json [ @@ -116,6 +118,7 @@ GET /projects/:id/merge_requests?state=all GET /projects/:id/merge_requests?iids[]=42&iids[]=43 GET /projects/:id/merge_requests?milestone=release GET /projects/:id/merge_requests?labels=bug,reproduced +GET /projects/:id/merge_requests?my_reaction_emoji=star ``` Parameters: @@ -135,6 +138,7 @@ Parameters: | `scope` | string | no | Return merge requests for the given scope: `created-by-me`, `assigned-to-me` or `all` _([Introduced][ce-13060] in GitLab 9.5)_ | | `author_id` | integer | no | Returns merge requests created by the given user `id` _([Introduced][ce-13060] in GitLab 9.5)_ | | `assignee_id` | integer | no | Returns merge requests assigned to the given user `id` _([Introduced][ce-13060] in GitLab 9.5)_ | +| `my_reaction_emoji` | string | no | Return merge requests reacted by the authenticated user by the given emoji ` _([Introduced][ce-14016] in GitLab 10.0)_ | ```json [ -- cgit v1.2.1 From 785834cfc098c1b74561c49823e2ac061e7d0269 Mon Sep 17 00:00:00 2001 From: Hiroyuki Sato Date: Tue, 5 Sep 2017 09:58:42 +0900 Subject: Fix API document --- doc/api/issues.md | 7 ++++--- doc/api/merge_requests.md | 35 ++++++++++++++++++----------------- 2 files changed, 22 insertions(+), 20 deletions(-) (limited to 'doc/api') diff --git a/doc/api/issues.md b/doc/api/issues.md index f8f9db484e2..8ca66049d31 100644 --- a/doc/api/issues.md +++ b/doc/api/issues.md @@ -41,7 +41,7 @@ GET /issues?my_reaction_emoji=star | `scope` | string | no | Return issues for the given scope: `created-by-me`, `assigned-to-me` or `all`. Defaults to `created-by-me` _([Introduced][ce-13004] in GitLab 9.5)_ | | `author_id` | integer | no | Return issues created by the given user `id`. Combine with `scope=all` or `scope=assigned-to-me`. _([Introduced][ce-13004] in GitLab 9.5)_ | | `assignee_id` | integer | no | Return issues assigned to the given user `id` _([Introduced][ce-13004] in GitLab 9.5)_ | -| `my_reaction_emoji` | string | no | Return issues reacted by the authenticated user by the given emoji ` _([Introduced][ce-14016] in GitLab 10.0)_ | +| `my_reaction_emoji` | string | no | Return issues reacted by the authenticated user by the given `emoji` _([Introduced][ce-14016] in GitLab 10.0)_ | | `iids[]` | Array[integer] | no | Return only the issues having the given `iid` | | `order_by` | string | no | Return issues ordered by `created_at` or `updated_at` fields. Default is `created_at` | | `sort` | string | no | Return issues sorted in `asc` or `desc` order. Default is `desc` | @@ -146,7 +146,7 @@ GET /groups/:id/issues?my_reaction_emoji=star | `scope` | string | no | Return issues for the given scope: `created-by-me`, `assigned-to-me` or `all` _([Introduced][ce-13004] in GitLab 9.5)_ | | `author_id` | integer | no | Return issues created by the given user `id` _([Introduced][ce-13004] in GitLab 9.5)_ | | `assignee_id` | integer | no | Return issues assigned to the given user `id` _([Introduced][ce-13004] in GitLab 9.5)_ | -| `my_reaction_emoji` | string | no | Return issues reacted by the authenticated user by the given emoji ` _([Introduced][ce-14016] in GitLab 10.0)_ | +| `my_reaction_emoji` | string | no | Return issues reacted by the authenticated user by the given `emoji` _([Introduced][ce-14016] in GitLab 10.0)_ | | `order_by` | string | no | Return issues ordered by `created_at` or `updated_at` fields. Default is `created_at` | | `sort` | string | no | Return issues sorted in `asc` or `desc` order. Default is `desc` | | `search` | string | no | Search group issues against their `title` and `description` | @@ -251,7 +251,7 @@ GET /projects/:id/issues?my_reaction_emoji=star | `scope` | string | no | Return issues for the given scope: `created-by-me`, `assigned-to-me` or `all` _([Introduced][ce-13004] in GitLab 9.5)_ | | `author_id` | integer | no | Return issues created by the given user `id` _([Introduced][ce-13004] in GitLab 9.5)_ | | `assignee_id` | integer | no | Return issues assigned to the given user `id` _([Introduced][ce-13004] in GitLab 9.5)_ | -| `my_reaction_emoji` | string | no | Return issues reacted by the authenticated user by the given emoji ` _([Introduced][ce-14016] in GitLab 10.0)_ | +| `my_reaction_emoji` | string | no | Return issues reacted by the authenticated user by the given `emoji` _([Introduced][ce-14016] in GitLab 10.0)_ | | `order_by` | string | no | Return issues ordered by `created_at` or `updated_at` fields. Default is `created_at` | | `sort` | string | no | Return issues sorted in `asc` or `desc` order. Default is `desc` | | `search` | string | no | Search project issues against their `title` and `description` | @@ -1099,3 +1099,4 @@ Example response: ``` [ce-13004]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/13004 +[ce-14016]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/14016 diff --git a/doc/api/merge_requests.md b/doc/api/merge_requests.md index a0b31d3633c..bff8a2d3e4d 100644 --- a/doc/api/merge_requests.md +++ b/doc/api/merge_requests.md @@ -41,7 +41,7 @@ Parameters: | `scope` | string | no | Return merge requests for the given scope: `created-by-me`, `assigned-to-me` or `all`. Defaults to `created-by-me` | | `author_id` | integer | no | Returns merge requests created by the given user `id`. Combine with `scope=all` or `scope=assigned-to-me` | | `assignee_id` | integer | no | Returns merge requests assigned to the given user `id` | -| `my_reaction_emoji` | string | no | Return merge requests reacted by the authenticated user by the given emoji ` _([Introduced][ce-14016] in GitLab 10.0)_ | +| `my_reaction_emoji` | string | no | Return merge requests reacted by the authenticated user by the given `emoji` _([Introduced][ce-14016] in GitLab 10.0)_ | ```json [ @@ -123,22 +123,22 @@ GET /projects/:id/merge_requests?my_reaction_emoji=star Parameters: -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of a project | -| `iids[]` | Array[integer] | no | Return the request having the given `iid` | -| `state` | string | no | Return all merge requests or just those that are `opened`, `closed`, or `merged`| -| `order_by`| string | no | Return requests ordered by `created_at` or `updated_at` fields. Default is `created_at` | -| `sort` | string | no | Return requests sorted in `asc` or `desc` order. Default is `desc` | -| `milestone` | string | no | Return merge requests for a specific milestone | -| `view` | string | no | If `simple`, returns the `iid`, URL, title, description, and basic state of merge request | -| `labels` | string | no | Return merge requests matching a comma separated list of labels | -| `created_after` | datetime | no | Return merge requests created after the given time (inclusive) | -| `created_before` | datetime | no | Return merge requests created before the given time (inclusive) | -| `scope` | string | no | Return merge requests for the given scope: `created-by-me`, `assigned-to-me` or `all` _([Introduced][ce-13060] in GitLab 9.5)_ | -| `author_id` | integer | no | Returns merge requests created by the given user `id` _([Introduced][ce-13060] in GitLab 9.5)_ | -| `assignee_id` | integer | no | Returns merge requests assigned to the given user `id` _([Introduced][ce-13060] in GitLab 9.5)_ | -| `my_reaction_emoji` | string | no | Return merge requests reacted by the authenticated user by the given emoji ` _([Introduced][ce-14016] in GitLab 10.0)_ | +| Attribute | Type | Required | Description | +| ------------------- | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------ | +| `id` | integer | yes | The ID of a project | +| `iids[]` | Array[integer] | no | Return the request having the given `iid` | +| `state` | string | no | Return all merge requests or just those that are `opened`, `closed`, or `merged` | +| `order_by` | string | no | Return requests ordered by `created_at` or `updated_at` fields. Default is `created_at` | +| `sort` | string | no | Return requests sorted in `asc` or `desc` order. Default is `desc` | +| `milestone` | string | no | Return merge requests for a specific milestone | +| `view` | string | no | If `simple`, returns the `iid`, URL, title, description, and basic state of merge request | +| `labels` | string | no | Return merge requests matching a comma separated list of labels | +| `created_after` | datetime | no | Return merge requests created after the given time (inclusive) | +| `created_before` | datetime | no | Return merge requests created before the given time (inclusive) | +| `scope` | string | no | Return merge requests for the given scope: `created-by-me`, `assigned-to-me` or `all` _([Introduced][ce-13060] in GitLab 9.5)_ | +| `author_id` | integer | no | Returns merge requests created by the given user `id` _([Introduced][ce-13060] in GitLab 9.5)_ | +| `assignee_id` | integer | no | Returns merge requests assigned to the given user `id` _([Introduced][ce-13060] in GitLab 9.5)_ | +| `my_reaction_emoji` | string | no | Return merge requests reacted by the authenticated user by the given `emoji` _([Introduced][ce-14016] in GitLab 10.0)_ | ```json [ @@ -1319,3 +1319,4 @@ Example response: ``` [ce-13060]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/13060 +[ce-14016]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/14016 -- cgit v1.2.1 From f4834c8ad5cd09ef4ed2be47eb2123cc06f05f6c Mon Sep 17 00:00:00 2001 From: Robert Schilling Date: Tue, 5 Sep 2017 11:32:27 +0200 Subject: Add documentation --- doc/api/users.md | 211 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 211 insertions(+) (limited to 'doc/api') diff --git a/doc/api/users.md b/doc/api/users.md index 57a13eb477d..57b4e117cf3 100644 --- a/doc/api/users.md +++ b/doc/api/users.md @@ -550,6 +550,217 @@ Parameters: Will return `200 OK` on success, or `404 Not found` if either user or key cannot be found. +## List all GPG keys + +Get a list of currently authenticated user's GPG keys. + +``` +GET /user/gpg_keys +``` + +```bash +curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/user/gpg_keys +``` + +Example response: + +```json +[ + { + "id": 1, + "key": "-----BEGIN PGP PUBLIC KEY BLOCK-----\r\n\r\nxsBNBFVjnlIBCACibzXOLCiZiL2oyzYUaTOCkYnSUhymg3pdbfKtd4mpBa58xKBj\r\nt1pTHVpw3Sk03wmzhM/Ndlt1AV2YhLv++83WKr+gAHFYFiCV/tnY8bx3HqvVoy8O\r\nCfxWhw4QZK7+oYzVmJj8ZJm3ZjOC4pzuegNWlNLCUdZDx9OKlHVXLCX1iUbjdYWa\r\nqKV6tdV8hZolkbyjedQgrpvoWyeSHHpwHF7yk4gNJWMMI5rpcssL7i6mMXb/sDzO\r\nVaAtU5wiVducsOa01InRFf7QSTxoAm6Xy0PGv/k48M6xCALa9nY+BzlOv47jUT57\r\nvilf4Szy9dKD0v9S0mQ+IHB+gNukWrnwtXx5ABEBAAHNFm5hbWUgKGNvbW1lbnQp\r\nIDxlbUBpbD7CwHUEEwECACkFAlVjnlIJEINgJNgv009/AhsDAhkBBgsJCAcDAgYV\r\nCAIJCgsEFgIDAQAAxqMIAFBHuBA8P1v8DtHonIK8Lx2qU23t8Mh68HBIkSjk2H7/\r\noO2cDWCw50jZ9D91PXOOyMPvBWV2IE3tARzCvnNGtzEFRtpIEtZ0cuctxeIF1id5\r\ncrfzdMDsmZyRHAOoZ9VtuD6mzj0ybQWMACb7eIHjZDCee3Slh3TVrLy06YRdq2I4\r\nbjMOPePtK5xnIpHGpAXkB3IONxyITpSLKsA4hCeP7gVvm7r7TuQg1ygiUBlWbBYn\r\niE5ROzqZjG1s7dQNZK/riiU2umGqGuwAb2IPvNiyuGR3cIgRE4llXH/rLuUlspAp\r\no4nlxaz65VucmNbN1aMbDXLJVSqR1DuE00vEsL1AItI=\r\n=XQoy\r\n-----END PGP PUBLIC KEY BLOCK-----", + "created_at": "2017-09-05T09:17:46.264Z" + } +] +``` + +## Get a specific GPG key + +Get a specific GPG key of currently authenticated user. + +``` +GET /user/gpg_keys/:key_id +``` + +Parameters: + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `key_id` | integer | yes | The ID of the GPG key | + +```bash +curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/user/gpg_keys/1 +``` + +Example response: + +```json + { + "id": 1, + "key": "-----BEGIN PGP PUBLIC KEY BLOCK-----\r\n\r\nxsBNBFVjnlIBCACibzXOLCiZiL2oyzYUaTOCkYnSUhymg3pdbfKtd4mpBa58xKBj\r\nt1pTHVpw3Sk03wmzhM/Ndlt1AV2YhLv++83WKr+gAHFYFiCV/tnY8bx3HqvVoy8O\r\nCfxWhw4QZK7+oYzVmJj8ZJm3ZjOC4pzuegNWlNLCUdZDx9OKlHVXLCX1iUbjdYWa\r\nqKV6tdV8hZolkbyjedQgrpvoWyeSHHpwHF7yk4gNJWMMI5rpcssL7i6mMXb/sDzO\r\nVaAtU5wiVducsOa01InRFf7QSTxoAm6Xy0PGv/k48M6xCALa9nY+BzlOv47jUT57\r\nvilf4Szy9dKD0v9S0mQ+IHB+gNukWrnwtXx5ABEBAAHNFm5hbWUgKGNvbW1lbnQp\r\nIDxlbUBpbD7CwHUEEwECACkFAlVjnlIJEINgJNgv009/AhsDAhkBBgsJCAcDAgYV\r\nCAIJCgsEFgIDAQAAxqMIAFBHuBA8P1v8DtHonIK8Lx2qU23t8Mh68HBIkSjk2H7/\r\noO2cDWCw50jZ9D91PXOOyMPvBWV2IE3tARzCvnNGtzEFRtpIEtZ0cuctxeIF1id5\r\ncrfzdMDsmZyRHAOoZ9VtuD6mzj0ybQWMACb7eIHjZDCee3Slh3TVrLy06YRdq2I4\r\nbjMOPePtK5xnIpHGpAXkB3IONxyITpSLKsA4hCeP7gVvm7r7TuQg1ygiUBlWbBYn\r\niE5ROzqZjG1s7dQNZK/riiU2umGqGuwAb2IPvNiyuGR3cIgRE4llXH/rLuUlspAp\r\no4nlxaz65VucmNbN1aMbDXLJVSqR1DuE00vEsL1AItI=\r\n=XQoy\r\n-----END PGP PUBLIC KEY BLOCK-----", + "created_at": "2017-09-05T09:17:46.264Z" + } +``` + +## Add a GPG key + +Creates a new GPG key owned by the currently authenticated user. + +``` +POST /user/gpg_keys +``` + +Parameters: + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| key | string | yes | The new GPG key | + +```bash +curl --data "key=-----BEGIN PGP PUBLIC KEY BLOCK-----\r\n\r\nxsBNBFV..." --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/user/gpg_keys +``` + +Example response: + +```json +[ + { + "id": 1, + "key": "-----BEGIN PGP PUBLIC KEY BLOCK-----\r\n\r\nxsBNBFVjnlIBCACibzXOLCiZiL2oyzYUaTOCkYnSUhymg3pdbfKtd4mpBa58xKBj\r\nt1pTHVpw3Sk03wmzhM/Ndlt1AV2YhLv++83WKr+gAHFYFiCV/tnY8bx3HqvVoy8O\r\nCfxWhw4QZK7+oYzVmJj8ZJm3ZjOC4pzuegNWlNLCUdZDx9OKlHVXLCX1iUbjdYWa\r\nqKV6tdV8hZolkbyjedQgrpvoWyeSHHpwHF7yk4gNJWMMI5rpcssL7i6mMXb/sDzO\r\nVaAtU5wiVducsOa01InRFf7QSTxoAm6Xy0PGv/k48M6xCALa9nY+BzlOv47jUT57\r\nvilf4Szy9dKD0v9S0mQ+IHB+gNukWrnwtXx5ABEBAAHNFm5hbWUgKGNvbW1lbnQp\r\nIDxlbUBpbD7CwHUEEwECACkFAlVjnlIJEINgJNgv009/AhsDAhkBBgsJCAcDAgYV\r\nCAIJCgsEFgIDAQAAxqMIAFBHuBA8P1v8DtHonIK8Lx2qU23t8Mh68HBIkSjk2H7/\r\noO2cDWCw50jZ9D91PXOOyMPvBWV2IE3tARzCvnNGtzEFRtpIEtZ0cuctxeIF1id5\r\ncrfzdMDsmZyRHAOoZ9VtuD6mzj0ybQWMACb7eIHjZDCee3Slh3TVrLy06YRdq2I4\r\nbjMOPePtK5xnIpHGpAXkB3IONxyITpSLKsA4hCeP7gVvm7r7TuQg1ygiUBlWbBYn\r\niE5ROzqZjG1s7dQNZK/riiU2umGqGuwAb2IPvNiyuGR3cIgRE4llXH/rLuUlspAp\r\no4nlxaz65VucmNbN1aMbDXLJVSqR1DuE00vEsL1AItI=\r\n=XQoy\r\n-----END PGP PUBLIC KEY BLOCK-----", + "created_at": "2017-09-05T09:17:46.264Z" + } +] +``` + +## Delete a GPG key + +Delete a GPG key owned by currently authenticated user. + +``` +DELETE /user/gpg_keys/:key_id +``` + +Parameters: + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `key_id` | integer | yes | The ID of the GPG key | + +```bash +curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/user/gpg_keys/1 +``` + +Returns `204 No Content` on success, or `404 Not found` if the key cannot be found. + +## List all GPG keys for given user + +Get a list of a specified user's GPG keys. Available only for admins. + +``` +GET /users/:id/gpg_keys +``` + +Parameters: + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer | yes | The ID of the user | + +```bash +curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/users/2/gpg_keys +``` + +Example response: + +```json +[ + { + "id": 1, + "key": "-----BEGIN PGP PUBLIC KEY BLOCK-----\r\n\r\nxsBNBFVjnlIBCACibzXOLCiZiL2oyzYUaTOCkYnSUhymg3pdbfKtd4mpBa58xKBj\r\nt1pTHVpw3Sk03wmzhM/Ndlt1AV2YhLv++83WKr+gAHFYFiCV/tnY8bx3HqvVoy8O\r\nCfxWhw4QZK7+oYzVmJj8ZJm3ZjOC4pzuegNWlNLCUdZDx9OKlHVXLCX1iUbjdYWa\r\nqKV6tdV8hZolkbyjedQgrpvoWyeSHHpwHF7yk4gNJWMMI5rpcssL7i6mMXb/sDzO\r\nVaAtU5wiVducsOa01InRFf7QSTxoAm6Xy0PGv/k48M6xCALa9nY+BzlOv47jUT57\r\nvilf4Szy9dKD0v9S0mQ+IHB+gNukWrnwtXx5ABEBAAHNFm5hbWUgKGNvbW1lbnQp\r\nIDxlbUBpbD7CwHUEEwECACkFAlVjnlIJEINgJNgv009/AhsDAhkBBgsJCAcDAgYV\r\nCAIJCgsEFgIDAQAAxqMIAFBHuBA8P1v8DtHonIK8Lx2qU23t8Mh68HBIkSjk2H7/\r\noO2cDWCw50jZ9D91PXOOyMPvBWV2IE3tARzCvnNGtzEFRtpIEtZ0cuctxeIF1id5\r\ncrfzdMDsmZyRHAOoZ9VtuD6mzj0ybQWMACb7eIHjZDCee3Slh3TVrLy06YRdq2I4\r\nbjMOPePtK5xnIpHGpAXkB3IONxyITpSLKsA4hCeP7gVvm7r7TuQg1ygiUBlWbBYn\r\niE5ROzqZjG1s7dQNZK/riiU2umGqGuwAb2IPvNiyuGR3cIgRE4llXH/rLuUlspAp\r\no4nlxaz65VucmNbN1aMbDXLJVSqR1DuE00vEsL1AItI=\r\n=XQoy\r\n-----END PGP PUBLIC KEY BLOCK-----", + "created_at": "2017-09-05T09:17:46.264Z" + } +] +``` + +## Get a specific GPG key for a given user + +Get a specific GPG key for a given user. Available only for admins. + +``` +GET /users/:id/gpg_keys/:key_id +``` + +Parameters: + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer | yes | The ID of the user | +| `key_id` | integer | yes | The ID of the GPG key | + +```bash +curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/users/2/gpg_keys/1 +``` + +Example response: + +```json + { + "id": 1, + "key": "-----BEGIN PGP PUBLIC KEY BLOCK-----\r\n\r\nxsBNBFVjnlIBCACibzXOLCiZiL2oyzYUaTOCkYnSUhymg3pdbfKtd4mpBa58xKBj\r\nt1pTHVpw3Sk03wmzhM/Ndlt1AV2YhLv++83WKr+gAHFYFiCV/tnY8bx3HqvVoy8O\r\nCfxWhw4QZK7+oYzVmJj8ZJm3ZjOC4pzuegNWlNLCUdZDx9OKlHVXLCX1iUbjdYWa\r\nqKV6tdV8hZolkbyjedQgrpvoWyeSHHpwHF7yk4gNJWMMI5rpcssL7i6mMXb/sDzO\r\nVaAtU5wiVducsOa01InRFf7QSTxoAm6Xy0PGv/k48M6xCALa9nY+BzlOv47jUT57\r\nvilf4Szy9dKD0v9S0mQ+IHB+gNukWrnwtXx5ABEBAAHNFm5hbWUgKGNvbW1lbnQp\r\nIDxlbUBpbD7CwHUEEwECACkFAlVjnlIJEINgJNgv009/AhsDAhkBBgsJCAcDAgYV\r\nCAIJCgsEFgIDAQAAxqMIAFBHuBA8P1v8DtHonIK8Lx2qU23t8Mh68HBIkSjk2H7/\r\noO2cDWCw50jZ9D91PXOOyMPvBWV2IE3tARzCvnNGtzEFRtpIEtZ0cuctxeIF1id5\r\ncrfzdMDsmZyRHAOoZ9VtuD6mzj0ybQWMACb7eIHjZDCee3Slh3TVrLy06YRdq2I4\r\nbjMOPePtK5xnIpHGpAXkB3IONxyITpSLKsA4hCeP7gVvm7r7TuQg1ygiUBlWbBYn\r\niE5ROzqZjG1s7dQNZK/riiU2umGqGuwAb2IPvNiyuGR3cIgRE4llXH/rLuUlspAp\r\no4nlxaz65VucmNbN1aMbDXLJVSqR1DuE00vEsL1AItI=\r\n=XQoy\r\n-----END PGP PUBLIC KEY BLOCK-----", + "created_at": "2017-09-05T09:17:46.264Z" + } +``` + +## Add a GPG key for a given user + +Create new GPG key owned by the specified user. Available only for admins. + +``` +POST /users/:id/gpg_keys +``` + +Parameters: + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer | yes | The ID of the user | +| `key_id` | integer | yes | The ID of the GPG key | + +```bash +curl --data "key=-----BEGIN PGP PUBLIC KEY BLOCK-----\r\n\r\nxsBNBFV..." --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/users/2/gpg_keys +``` + +Example response: + +```json +[ + { + "id": 1, + "key": "-----BEGIN PGP PUBLIC KEY BLOCK-----\r\n\r\nxsBNBFVjnlIBCACibzXOLCiZiL2oyzYUaTOCkYnSUhymg3pdbfKtd4mpBa58xKBj\r\nt1pTHVpw3Sk03wmzhM/Ndlt1AV2YhLv++83WKr+gAHFYFiCV/tnY8bx3HqvVoy8O\r\nCfxWhw4QZK7+oYzVmJj8ZJm3ZjOC4pzuegNWlNLCUdZDx9OKlHVXLCX1iUbjdYWa\r\nqKV6tdV8hZolkbyjedQgrpvoWyeSHHpwHF7yk4gNJWMMI5rpcssL7i6mMXb/sDzO\r\nVaAtU5wiVducsOa01InRFf7QSTxoAm6Xy0PGv/k48M6xCALa9nY+BzlOv47jUT57\r\nvilf4Szy9dKD0v9S0mQ+IHB+gNukWrnwtXx5ABEBAAHNFm5hbWUgKGNvbW1lbnQp\r\nIDxlbUBpbD7CwHUEEwECACkFAlVjnlIJEINgJNgv009/AhsDAhkBBgsJCAcDAgYV\r\nCAIJCgsEFgIDAQAAxqMIAFBHuBA8P1v8DtHonIK8Lx2qU23t8Mh68HBIkSjk2H7/\r\noO2cDWCw50jZ9D91PXOOyMPvBWV2IE3tARzCvnNGtzEFRtpIEtZ0cuctxeIF1id5\r\ncrfzdMDsmZyRHAOoZ9VtuD6mzj0ybQWMACb7eIHjZDCee3Slh3TVrLy06YRdq2I4\r\nbjMOPePtK5xnIpHGpAXkB3IONxyITpSLKsA4hCeP7gVvm7r7TuQg1ygiUBlWbBYn\r\niE5ROzqZjG1s7dQNZK/riiU2umGqGuwAb2IPvNiyuGR3cIgRE4llXH/rLuUlspAp\r\no4nlxaz65VucmNbN1aMbDXLJVSqR1DuE00vEsL1AItI=\r\n=XQoy\r\n-----END PGP PUBLIC KEY BLOCK-----", + "created_at": "2017-09-05T09:17:46.264Z" + } +] +``` + +## Delete a GPG key for a given user + +Delete a GPG key owned by a specified user. Available only for admins. + +``` +DELETE /users/:id/gpg_keys/:key_id +``` + +Parameters: + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer | yes | The ID of the user | +| `key_id` | integer | yes | The ID of the GPG key | + +```bash +curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/users/2/gpg_keys/1 +``` + ## List emails Get a list of currently authenticated user's emails. -- cgit v1.2.1 From abeae9f4e61c4c9da8001fa858441cf64ea0e0d5 Mon Sep 17 00:00:00 2001 From: Jacob Schatz Date: Tue, 5 Sep 2017 15:35:58 -0400 Subject: Remove GraphQL from future plans. --- doc/api/README.md | 13 ------------- 1 file changed, 13 deletions(-) (limited to 'doc/api') diff --git a/doc/api/README.md b/doc/api/README.md index c2a08dcff07..d3b7c9e6ef1 100644 --- a/doc/api/README.md +++ b/doc/api/README.md @@ -59,19 +59,6 @@ following locations: - [V3 to V4](v3_to_v4.md) - [Version](version.md) -## Road to GraphQL - -Going forward, we will start on moving to -[GraphQL](http://graphql.org/learn/best-practices/) and deprecate the use of -controller-specific endpoints. GraphQL has a number of benefits: - -1. We avoid having to maintain two different APIs. -2. Callers of the API can request only what they need. -3. It is versioned by default. - -It will co-exist with the current v4 REST API. If we have a v5 API, this should -be a compatibility layer on top of GraphQL. - ## Basic usage API requests should be prefixed with `api` and the API version. The API version -- cgit v1.2.1 From f58a1bdb0e6a9b308509c7576431cade7d9d65b4 Mon Sep 17 00:00:00 2001 From: Jacob Schatz Date: Tue, 5 Sep 2017 15:49:17 -0400 Subject: Provide context for people wondering what happened. --- doc/api/README.md | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'doc/api') diff --git a/doc/api/README.md b/doc/api/README.md index d3b7c9e6ef1..357248cdaf1 100644 --- a/doc/api/README.md +++ b/doc/api/README.md @@ -59,6 +59,10 @@ following locations: - [V3 to V4](v3_to_v4.md) - [Version](version.md) +## Road to GraphQL + +After reviewing the GraphQL license, we have changed our plans to move our API to GraphQL. Anything related to the Facebook BSD plus patent license will not be allowed at GitLab. + ## Basic usage API requests should be prefixed with `api` and the API version. The API version -- cgit v1.2.1 From a728e4d7c031e89addea094fdc1b68ce10edd64b Mon Sep 17 00:00:00 2001 From: Jacob Schatz Date: Tue, 5 Sep 2017 15:51:04 -0400 Subject: Update wording on change plans. --- doc/api/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/api') diff --git a/doc/api/README.md b/doc/api/README.md index 357248cdaf1..a947eed2db8 100644 --- a/doc/api/README.md +++ b/doc/api/README.md @@ -61,7 +61,7 @@ following locations: ## Road to GraphQL -After reviewing the GraphQL license, we have changed our plans to move our API to GraphQL. Anything related to the Facebook BSD plus patent license will not be allowed at GitLab. +We have changed our plans to move to GraphQL. After reviewing the GraphQL license, anything related to the Facebook BSD plus patent license will not be allowed at GitLab. ## Basic usage -- cgit v1.2.1 From 4dff341af11d651d1ec199d35eebaf4adb92fdd0 Mon Sep 17 00:00:00 2001 From: Robert Schilling Date: Wed, 6 Sep 2017 09:15:34 +0200 Subject: Fix wrong API status codes --- doc/api/README.md | 4 ++-- doc/api/environments.md | 2 +- doc/api/project_snippets.md | 3 +-- doc/api/users.md | 15 +++------------ 4 files changed, 7 insertions(+), 17 deletions(-) (limited to 'doc/api') diff --git a/doc/api/README.md b/doc/api/README.md index a947eed2db8..db61497db53 100644 --- a/doc/api/README.md +++ b/doc/api/README.md @@ -237,8 +237,8 @@ The following table gives an overview of how the API functions generally behave. | ------------ | ----------- | | `GET` | Access one or more resources and return the result as JSON. | | `POST` | Return `201 Created` if the resource is successfully created and return the newly created resource as JSON. | -| `GET` / `PUT` / `DELETE` | Return `200 OK` if the resource is accessed, modified or deleted successfully. The (modified) result is returned as JSON. | -| `DELETE` | Designed to be idempotent, meaning a request to a resource still returns `200 OK` even it was deleted before or is not available. The reasoning behind this, is that the user is not really interested if the resource existed before or not. | +| `GET` / `PUT` | Return `200 OK` if the resource is accessed or modified successfully. The (modified) result is returned as JSON. | +| `DELETE` | Returns `204 No Content` if the resuource was deleted successfully. | The following table shows the possible return codes for API requests. diff --git a/doc/api/environments.md b/doc/api/environments.md index 5ca766bf87d..e8deb3e07e9 100644 --- a/doc/api/environments.md +++ b/doc/api/environments.md @@ -94,7 +94,7 @@ Example response: ## Delete an environment -It returns `200` if the environment was successfully deleted, and `404` if the environment does not exist. +It returns `204` if the environment was successfully deleted, and `404` if the environment does not exist. ``` DELETE /projects/:id/environments/:environment_id diff --git a/doc/api/project_snippets.md b/doc/api/project_snippets.md index 24c8ff5fa7a..ad2521230e6 100644 --- a/doc/api/project_snippets.md +++ b/doc/api/project_snippets.md @@ -95,8 +95,7 @@ Parameters: ## Delete snippet -Deletes an existing project snippet. This is an idempotent function and deleting a non-existent -snippet still returns a `200 OK` status code. +Deletes an existing project snippet. This returns a `204 No Content` status code if the operation was successfully or `404` if the resource was not found. ``` DELETE /projects/:id/snippets/:snippet_id diff --git a/doc/api/users.md b/doc/api/users.md index 57b4e117cf3..9f3e4caf2f4 100644 --- a/doc/api/users.md +++ b/doc/api/users.md @@ -299,10 +299,7 @@ e.g. when renaming the email address to some existing one. ## User deletion Deletes a user. Available only for administrators. -This is an idempotent function, calling this function for a non-existent user id -still returns a status code `200 OK`. -The JSON response differs if the user was actually deleted or not. -In the former the user is returned and in the latter not. +This returns a `204 No Content` status code if the operation was successfully or `404` if the resource was not found. ``` DELETE /users/:id @@ -524,8 +521,7 @@ Parameters: ## Delete SSH key for current user Deletes key owned by currently authenticated user. -This is an idempotent function and calling it on a key that is already deleted -or not available results in `200 OK`. +This returns a `204 No Content` status code if the operation was successfully or `404` if the resource was not found. ``` DELETE /user/keys/:key_id @@ -548,8 +544,6 @@ Parameters: - `id` (required) - id of specified user - `key_id` (required) - SSH key ID -Will return `200 OK` on success, or `404 Not found` if either user or key cannot be found. - ## List all GPG keys Get a list of currently authenticated user's GPG keys. @@ -865,8 +859,7 @@ Parameters: ## Delete email for current user Deletes email owned by currently authenticated user. -This is an idempotent function and calling it on a email that is already deleted -or not available results in `200 OK`. +This returns a `204 No Content` status code if the operation was successfully or `404` if the resource was not found. ``` DELETE /user/emails/:email_id @@ -889,8 +882,6 @@ Parameters: - `id` (required) - id of specified user - `email_id` (required) - email ID -Will return `200 OK` on success, or `404 Not found` if either user or email cannot be found. - ## Block user Blocks the specified user. Available only for admin. -- cgit v1.2.1 From 2247f11afddfab3ded9501a43c840a2e789ee13d Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Wed, 6 Sep 2017 10:21:16 +0200 Subject: Clean up projects API docs --- doc/api/projects.md | 227 +++++++++------------------------------------------- 1 file changed, 40 insertions(+), 187 deletions(-) (limited to 'doc/api') diff --git a/doc/api/projects.md b/doc/api/projects.md index d3f8e509612..67f700d5fb4 100644 --- a/doc/api/projects.md +++ b/doc/api/projects.md @@ -1,6 +1,6 @@ # Projects API -### Project visibility level +## Project visibility level Project in GitLab can be either private, internal or public. This is determined by the `visibility` field in the project. @@ -16,16 +16,15 @@ Values for the project visibility level are: * `public`: The project can be cloned without any authentication. -## List projects +## List all projects -Get a list of visible projects for authenticated user. When accessed without authentication, only public projects are returned. +Get a list of all visible projects across GitLab for the authenticated user. +When accessed without authentication, only public projects are returned. ``` GET /projects ``` -Parameters: - | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | | `archived` | boolean | no | Limit by archived status | @@ -191,16 +190,15 @@ Parameters: ] ``` -### List a user's projects +## List user projects -Get a list of visible projects for the given user. When accessed without authentication, only public projects are returned. +Get a list of visible projects for the given user. When accessed without +authentication, only public projects are returned. ``` GET /users/:user_id/projects ``` -Parameters: - | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | | `user_id` | string | yes | The ID or username of the user | @@ -367,7 +365,7 @@ Parameters: ] ``` -### Get single project +## Get single project Get a specific project. This endpoint can be accessed without authentication if the project is publicly accessible. @@ -376,8 +374,6 @@ the project is publicly accessible. GET /projects/:id ``` -Parameters: - | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | @@ -480,17 +476,14 @@ Parameters: Get the users list of a project. - -Parameters: +``` +GET /projects/:id/users +``` | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | | `search` | string | no | Search for specific users | -``` -GET /projects/:id/users -``` - ```json [ { @@ -512,11 +505,11 @@ GET /projects/:id/users ] ``` -### Get project events +## Get project events -Please refer to the [Events API documentation](events.md#list-a-projects-visible-events) +Please refer to the [Events API documentation](events.md#list-a-projects-visible-events). -### Create project +## Create project Creates a new project owned by the authenticated user. @@ -524,8 +517,6 @@ Creates a new project owned by the authenticated user. POST /projects ``` -Parameters: - | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | | `name` | string | yes if path is not provided | The name of the new project. Equals path if not provided. | @@ -551,7 +542,7 @@ Parameters: | `printing_merge_request_link_enabled` | boolean | no | Show link to create/view merge request when pushing from the command line | | `ci_config_path` | string | no | The path to CI config file | -### Create project for user +## Create project for user Creates a new project owned by the specified user. Available only for admins. @@ -559,8 +550,6 @@ Creates a new project owned by the specified user. Available only for admins. POST /projects/user/:user_id ``` -Parameters: - | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | | `user_id` | integer | yes | The user ID of the project owner | @@ -588,7 +577,7 @@ Parameters: | `printing_merge_request_link_enabled` | boolean | no | Show link to create/view merge request when pushing from the command line | | `ci_config_path` | string | no | The path to CI config file | -### Edit project +## Edit project Updates an existing project. @@ -596,8 +585,6 @@ Updates an existing project. PUT /projects/:id ``` -Parameters: - | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | @@ -623,24 +610,24 @@ Parameters: | `avatar` | mixed | no | Image file for avatar of the project | | `ci_config_path` | string | no | The path to CI config file | -### Fork project +## Fork project Forks a project into the user namespace of the authenticated user or the one provided. -The forking operation for a project is asynchronous and is completed in a background job. The request will return immediately. To determine whether the fork of the project has completed, query the `import_status` for the new project. +The forking operation for a project is asynchronous and is completed in a +background job. The request will return immediately. To determine whether the +fork of the project has completed, query the `import_status` for the new project. ``` POST /projects/:id/fork ``` -Parameters: - | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | | `namespace` | integer/string | yes | The ID or path of the namespace that the project will be forked to | -### Star a project +## Star a project Stars a given project. Returns status code `304` if the project is already starred. @@ -648,8 +635,6 @@ Stars a given project. Returns status code `304` if the project is already starr POST /projects/:id/star ``` -Parameters: - | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | @@ -717,7 +702,7 @@ Example response: } ``` -### Unstar a project +## Unstar a project Unstars a given project. Returns status code `304` if the project is not starred. @@ -792,7 +777,7 @@ Example response: } ``` -### Archive a project +## Archive a project 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. @@ -885,7 +870,7 @@ Example response: } ``` -### Unarchive a project +## Unarchive a project 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. @@ -978,7 +963,7 @@ Example response: } ``` -### Remove project +## Remove project Removes a project including all associated resources (issues, merge requests etc.) @@ -986,15 +971,11 @@ Removes a project including all associated resources (issues, merge requests etc DELETE /projects/:id ``` -Parameters: - | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | -## Uploads - -### Upload a file +## Upload a file Uploads a file to the specified project to be used in an issue or merge request description, or a comment. @@ -1002,8 +983,6 @@ Uploads a file to the specified project to be used in an issue or merge request POST /projects/:id/uploads ``` -Parameters: - | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | @@ -1028,15 +1007,11 @@ Returned object: } ``` -**Note**: The returned `url` is relative to the project path. +>**Note**: The returned `url` is relative to the project path. In Markdown contexts, the link is automatically expanded when the format in `markdown` is used. -## Project members - -Please consult the [Project Members](members.md) documentation. - -### Share project with group +## Share project with group Allow to share project with group. @@ -1044,8 +1019,6 @@ Allow to share project with group. POST /projects/:id/share ``` -Parameters: - | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | @@ -1053,7 +1026,7 @@ Parameters: | `group_access` | integer | yes | The permissions level to grant the group | | `expires_at` | string | no | Share expiration date in ISO 8601 format: 2016-09-26 | -### Delete a shared project link within a group +## Delete a shared project link within a group Unshare the project from the group. Returns `204` and no content on success. @@ -1061,8 +1034,6 @@ Unshare the project from the group. Returns `204` and no content on success. DELETE /projects/:id/share/:group_id ``` -Parameters: - | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | @@ -1085,8 +1056,6 @@ Get a list of project hooks. GET /projects/:id/hooks ``` -Parameters: - | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | @@ -1099,8 +1068,6 @@ Get a specific hook for a project. GET /projects/:id/hooks/:hook_id ``` -Parameters: - | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | @@ -1132,8 +1099,6 @@ Adds a hook to a specified project. POST /projects/:id/hooks ``` -Parameters: - | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | @@ -1157,8 +1122,6 @@ Edits a hook for a specified project. PUT /projects/:id/hooks/:hook_id ``` -Parameters: - | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | @@ -1184,8 +1147,6 @@ Either the hook is available or not. DELETE /projects/:id/hooks/:hook_id ``` -Parameters: - | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | @@ -1194,126 +1155,16 @@ Parameters: Note the JSON response differs if the hook is available or not. If the project hook is available before it is returned in the JSON response or an empty response is returned. -## Branches - -For more information please consult the [Branches](branches.md) documentation. - -### List branches - -Lists all branches of a project. - -``` -GET /projects/:id/repository/branches -``` - -Parameters: - -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | - -```json -[ - { - "name": "async", - "commit": { - "id": "a2b702edecdf41f07b42653eb1abe30ce98b9fca", - "parent_ids": [ - "3f94fc7c85061973edc9906ae170cc269b07ca55" - ], - "message": "give Caolan credit where it's due (up top)", - "author_name": "Jeremy Ashkenas", - "author_email": "jashkenas@example.com", - "authored_date": "2010-12-08T21:28:50+00:00", - "committer_name": "Jeremy Ashkenas", - "committer_email": "jashkenas@example.com", - "committed_date": "2010-12-08T21:28:50+00:00" - }, - "protected": false, - "developers_can_push": false, - "developers_can_merge": false - }, - { - "name": "gh-pages", - "commit": { - "id": "101c10a60019fe870d21868835f65c25d64968fc", - "parent_ids": [ - "9c15d2e26945a665131af5d7b6d30a06ba338aaa" - ], - "message": "Underscore.js 1.5.2", - "author_name": "Jeremy Ashkenas", - "author_email": "jashkenas@example.com", - "authored_date": "2013-09-07T12:58:21+00:00", - "committer_name": "Jeremy Ashkenas", - "committer_email": "jashkenas@example.com", - "committed_date": "2013-09-07T12:58:21+00:00" - }, - "protected": false, - "developers_can_push": false, - "developers_can_merge": false - } -] -``` - -### Single branch - -A specific branch of a project. - -``` -GET /projects/:id/repository/branches/:branch -``` - -Parameters: - -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | -| `branch` | string | yes | The name of the branch | -| `developers_can_push` | boolean | no | Flag if developers can push to the branch | -| `developers_can_merge` | boolean | no | Flag if developers can merge to the branch | - -### Protect single branch - -Protects a single branch of a project. - -``` -PUT /projects/:id/repository/branches/:branch/protect -``` - -Parameters: - -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | -| `branch` | string | yes | The name of the branch | - -### Unprotect single branch - -Unprotects a single branch of a project. - -``` -PUT /projects/:id/repository/branches/:branch/unprotect -``` - -Parameters: - -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | -| `branch` | string | yes | The name of the branch | - ## Admin fork relation Allows modification of the forked relationship between existing projects. Available only for admins. -### Create a forked from/to relation between existing projects. +### Create a forked from/to relation between existing projects ``` POST /projects/:id/fork/:forked_from_id ``` -Parameters: - | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | @@ -1325,8 +1176,6 @@ Parameters: DELETE /projects/:id/fork ``` -Parameter: - | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | @@ -1341,8 +1190,6 @@ accessible. GET /projects ``` -Parameters: - | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | | `search` | string | yes | A string contained in the project name | @@ -1355,14 +1202,20 @@ curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/a ## Start the Housekeeping task for a Project ->**Note:** This feature was introduced in GitLab 9.0 +> Introduced in GitLab 9.0. ``` POST /projects/:id/housekeeping ``` -Parameters: - | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID of the project or NAMESPACE/PROJECT_NAME | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | + +## Branches + +Read more in the [Branches](branches.md) documentation. + +## Project members + +Read more in the [Project members](members.md) documentation. -- cgit v1.2.1 From ef4b3a39bc705dfa47762868ea064d2dbadc16e6 Mon Sep 17 00:00:00 2001 From: Ashley Dumaine Date: Mon, 28 Aug 2017 17:38:06 -0400 Subject: Add functionality to collapse outdated diff comments regardless of discussion resolution --- doc/api/projects.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) (limited to 'doc/api') diff --git a/doc/api/projects.md b/doc/api/projects.md index d3f8e509612..345b88daa79 100644 --- a/doc/api/projects.md +++ b/doc/api/projects.md @@ -70,6 +70,7 @@ Parameters: "jobs_enabled": true, "wiki_enabled": true, "snippets_enabled": false, + "collapse_outdated_diff_comments": false, "container_registry_enabled": false, "created_at": "2013-09-30T13:46:02Z", "last_activity_at": "2013-09-30T13:46:02Z", @@ -137,6 +138,7 @@ Parameters: "jobs_enabled": true, "wiki_enabled": true, "snippets_enabled": false, + "collapse_outdated_diff_comments": false, "container_registry_enabled": false, "created_at": "2013-09-30T13:46:02Z", "last_activity_at": "2013-09-30T13:46:02Z", @@ -246,6 +248,7 @@ Parameters: "jobs_enabled": true, "wiki_enabled": true, "snippets_enabled": false, + "collapse_outdated_diff_comments": false, "container_registry_enabled": false, "created_at": "2013-09-30T13:46:02Z", "last_activity_at": "2013-09-30T13:46:02Z", @@ -313,6 +316,7 @@ Parameters: "jobs_enabled": true, "wiki_enabled": true, "snippets_enabled": false, + "collapse_outdated_diff_comments": false, "container_registry_enabled": false, "created_at": "2013-09-30T13:46:02Z", "last_activity_at": "2013-09-30T13:46:02Z", @@ -411,6 +415,7 @@ Parameters: "jobs_enabled": true, "wiki_enabled": true, "snippets_enabled": false, + "collapse_outdated_diff_comments": false, "container_registry_enabled": false, "created_at": "2013-09-30T13:46:02Z", "last_activity_at": "2013-09-30T13:46:02Z", @@ -537,6 +542,7 @@ Parameters: | `jobs_enabled` | boolean | no | Enable jobs for this project | | `wiki_enabled` | boolean | no | Enable wiki for this project | | `snippets_enabled` | boolean | no | Enable snippets for this project | +| `collapse_outdated_diff_comments` | boolean | no | Collapse outdated diffs regardless of discussion resolution | | `container_registry_enabled` | boolean | no | Enable container registry for this project | | `shared_runners_enabled` | boolean | no | Enable shared runners for this project | | `visibility` | string | no | See [project visibility level](#project-visibility-level) | @@ -574,6 +580,7 @@ Parameters: | `jobs_enabled` | boolean | no | Enable jobs for this project | | `wiki_enabled` | boolean | no | Enable wiki for this project | | `snippets_enabled` | boolean | no | Enable snippets for this project | +| `collapse_outdated_diff_comments` | boolean | no | Collapse outdated diffs regardless of discussion resolution | | `container_registry_enabled` | boolean | no | Enable container registry for this project | | `shared_runners_enabled` | boolean | no | Enable shared runners for this project | | `visibility` | string | no | See [project visibility level](#project-visibility-level) | @@ -610,6 +617,7 @@ Parameters: | `jobs_enabled` | boolean | no | Enable jobs for this project | | `wiki_enabled` | boolean | no | Enable wiki for this project | | `snippets_enabled` | boolean | no | Enable snippets for this project | +| `collapse_outdated_diff_comments` | boolean | no | Collapse outdated diffs regardless of discussion resolution | | `container_registry_enabled` | boolean | no | Enable container registry for this project | | `shared_runners_enabled` | boolean | no | Enable shared runners for this project | | `visibility` | string | no | See [project visibility level](#project-visibility-level) | @@ -683,6 +691,7 @@ Example response: "jobs_enabled": true, "wiki_enabled": true, "snippets_enabled": false, + "collapse_outdated_diff_comments": false, "container_registry_enabled": false, "created_at": "2013-09-30T13:46:02Z", "last_activity_at": "2013-09-30T13:46:02Z", @@ -758,6 +767,7 @@ Example response: "jobs_enabled": true, "wiki_enabled": true, "snippets_enabled": false, + "collapse_outdated_diff_comments": false, "container_registry_enabled": false, "created_at": "2013-09-30T13:46:02Z", "last_activity_at": "2013-09-30T13:46:02Z", @@ -839,6 +849,7 @@ Example response: "jobs_enabled": true, "wiki_enabled": true, "snippets_enabled": false, + "collapse_outdated_diff_comments": false, "container_registry_enabled": false, "created_at": "2013-09-30T13:46:02Z", "last_activity_at": "2013-09-30T13:46:02Z", @@ -932,6 +943,7 @@ Example response: "jobs_enabled": true, "wiki_enabled": true, "snippets_enabled": false, + "collapse_outdated_diff_comments": false, "container_registry_enabled": false, "created_at": "2013-09-30T13:46:02Z", "last_activity_at": "2013-09-30T13:46:02Z", -- cgit v1.2.1 From a3f76b76a4b8db85c6fa557a5e801dcea7195735 Mon Sep 17 00:00:00 2001 From: Ashley Dumaine Date: Fri, 1 Sep 2017 18:39:22 -0400 Subject: change collapse to resolve and comments to discussions --- doc/api/projects.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) (limited to 'doc/api') diff --git a/doc/api/projects.md b/doc/api/projects.md index 345b88daa79..2d973547d14 100644 --- a/doc/api/projects.md +++ b/doc/api/projects.md @@ -70,7 +70,7 @@ Parameters: "jobs_enabled": true, "wiki_enabled": true, "snippets_enabled": false, - "collapse_outdated_diff_comments": false, + "resolve_outdated_diff_discussions": false, "container_registry_enabled": false, "created_at": "2013-09-30T13:46:02Z", "last_activity_at": "2013-09-30T13:46:02Z", @@ -138,7 +138,7 @@ Parameters: "jobs_enabled": true, "wiki_enabled": true, "snippets_enabled": false, - "collapse_outdated_diff_comments": false, + "resolve_outdated_diff_discussions": false, "container_registry_enabled": false, "created_at": "2013-09-30T13:46:02Z", "last_activity_at": "2013-09-30T13:46:02Z", @@ -248,7 +248,7 @@ Parameters: "jobs_enabled": true, "wiki_enabled": true, "snippets_enabled": false, - "collapse_outdated_diff_comments": false, + "resolve_outdated_diff_discussions": false, "container_registry_enabled": false, "created_at": "2013-09-30T13:46:02Z", "last_activity_at": "2013-09-30T13:46:02Z", @@ -316,7 +316,7 @@ Parameters: "jobs_enabled": true, "wiki_enabled": true, "snippets_enabled": false, - "collapse_outdated_diff_comments": false, + "resolve_outdated_diff_discussions": false, "container_registry_enabled": false, "created_at": "2013-09-30T13:46:02Z", "last_activity_at": "2013-09-30T13:46:02Z", @@ -415,7 +415,7 @@ Parameters: "jobs_enabled": true, "wiki_enabled": true, "snippets_enabled": false, - "collapse_outdated_diff_comments": false, + "resolve_outdated_diff_discussions": false, "container_registry_enabled": false, "created_at": "2013-09-30T13:46:02Z", "last_activity_at": "2013-09-30T13:46:02Z", @@ -542,7 +542,7 @@ Parameters: | `jobs_enabled` | boolean | no | Enable jobs for this project | | `wiki_enabled` | boolean | no | Enable wiki for this project | | `snippets_enabled` | boolean | no | Enable snippets for this project | -| `collapse_outdated_diff_comments` | boolean | no | Collapse outdated diffs regardless of discussion resolution | +| `resolve_outdated_diff_discussions` | boolean | no | Automatically resolve merge request diffs discussions on lines changed with a push | | `container_registry_enabled` | boolean | no | Enable container registry for this project | | `shared_runners_enabled` | boolean | no | Enable shared runners for this project | | `visibility` | string | no | See [project visibility level](#project-visibility-level) | @@ -580,7 +580,7 @@ Parameters: | `jobs_enabled` | boolean | no | Enable jobs for this project | | `wiki_enabled` | boolean | no | Enable wiki for this project | | `snippets_enabled` | boolean | no | Enable snippets for this project | -| `collapse_outdated_diff_comments` | boolean | no | Collapse outdated diffs regardless of discussion resolution | +| `resolve_outdated_diff_discussions` | boolean | no | Automatically resolve merge request diffs discussions on lines changed with a push | | `container_registry_enabled` | boolean | no | Enable container registry for this project | | `shared_runners_enabled` | boolean | no | Enable shared runners for this project | | `visibility` | string | no | See [project visibility level](#project-visibility-level) | @@ -617,7 +617,7 @@ Parameters: | `jobs_enabled` | boolean | no | Enable jobs for this project | | `wiki_enabled` | boolean | no | Enable wiki for this project | | `snippets_enabled` | boolean | no | Enable snippets for this project | -| `collapse_outdated_diff_comments` | boolean | no | Collapse outdated diffs regardless of discussion resolution | +| `resolve_outdated_diff_discussions` | boolean | no | Automatically resolve merge request diffs discussions on lines changed with a push | | `container_registry_enabled` | boolean | no | Enable container registry for this project | | `shared_runners_enabled` | boolean | no | Enable shared runners for this project | | `visibility` | string | no | See [project visibility level](#project-visibility-level) | @@ -691,7 +691,7 @@ Example response: "jobs_enabled": true, "wiki_enabled": true, "snippets_enabled": false, - "collapse_outdated_diff_comments": false, + "resolve_outdated_diff_discussions": false, "container_registry_enabled": false, "created_at": "2013-09-30T13:46:02Z", "last_activity_at": "2013-09-30T13:46:02Z", @@ -767,7 +767,7 @@ Example response: "jobs_enabled": true, "wiki_enabled": true, "snippets_enabled": false, - "collapse_outdated_diff_comments": false, + "resolve_outdated_diff_discussions": false, "container_registry_enabled": false, "created_at": "2013-09-30T13:46:02Z", "last_activity_at": "2013-09-30T13:46:02Z", @@ -849,7 +849,7 @@ Example response: "jobs_enabled": true, "wiki_enabled": true, "snippets_enabled": false, - "collapse_outdated_diff_comments": false, + "resolve_outdated_diff_discussions": false, "container_registry_enabled": false, "created_at": "2013-09-30T13:46:02Z", "last_activity_at": "2013-09-30T13:46:02Z", @@ -943,7 +943,7 @@ Example response: "jobs_enabled": true, "wiki_enabled": true, "snippets_enabled": false, - "collapse_outdated_diff_comments": false, + "resolve_outdated_diff_discussions": false, "container_registry_enabled": false, "created_at": "2013-09-30T13:46:02Z", "last_activity_at": "2013-09-30T13:46:02Z", -- cgit v1.2.1 From 49e9e0b2a0ea0c1b8b6b472d320a63067bbbf79c Mon Sep 17 00:00:00 2001 From: Grzegorz Bizon Date: Wed, 6 Sep 2017 11:40:20 +0200 Subject: Add basic docs about new artifact access API endpoint --- doc/api/jobs.md | 38 ++++++++++++++++++++++++++++++++++++-- 1 file changed, 36 insertions(+), 2 deletions(-) (limited to 'doc/api') diff --git a/doc/api/jobs.md b/doc/api/jobs.md index 297115e94ac..d60c7c12881 100644 --- a/doc/api/jobs.md +++ b/doc/api/jobs.md @@ -320,11 +320,11 @@ Response: [ce-2893]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2893 -## Download the artifacts file +## Download the artifacts archive > [Introduced][ce-5347] in GitLab 8.10. -Download the artifacts file from the given reference name and job provided the +Download the artifacts archive from the given reference name and job provided the job finished successfully. ``` @@ -354,6 +354,40 @@ Example response: [ce-5347]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5347 +## Download a single artifact file + +> Introduced in GitLab 10.0 + +Download a single artifact file from within the job's artifacts archive. + +Only a single file is going to be extracted from the archive and streamed to a client. + +``` +GET /projects/:id/jobs/:job_id/artifacts/*artifact_path +``` + +Parameters + +| Attribute | Type | Required | Description | +|-----------------|---------|----------|-------------------------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | +| `job_id ` | integer | yes | The unique job identifier | +| `artifact_path` | string | yes | Path to a file inside the artifacts archive | + +Example request: + +``` +curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/1/jobs/5/artifacts/some/release/file.pdf" +``` + +Example response: + +| Status | Description | +|-----------|--------------------------------------| +| 200 | Sends a single artifact file | +| 400 | Invalid path provided | +| 404 | Build not found or no file/artifacts | + ## Get a trace file Get a trace of a specific job of a project -- cgit v1.2.1 From 6c49a628000605d1beb120431003abb329b9fd16 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rub=C3=A9n=20D=C3=A1vila?= Date: Thu, 17 Aug 2017 10:37:36 -0500 Subject: Restore some changes from !9199 --- doc/api/keys.md | 1 + doc/api/session.md | 1 + doc/api/users.md | 5 +++++ 3 files changed, 7 insertions(+) (limited to 'doc/api') diff --git a/doc/api/keys.md b/doc/api/keys.md index 376ac27df3a..ddcf7830621 100644 --- a/doc/api/keys.md +++ b/doc/api/keys.md @@ -32,6 +32,7 @@ Parameters: "twitter": "", "website_url": "", "email": "john@example.com", + "theme_id": 2, "color_scheme_id": 1, "projects_limit": 10, "current_sign_in_at": null, diff --git a/doc/api/session.md b/doc/api/session.md index f79eac11689..b97e26f34a2 100644 --- a/doc/api/session.md +++ b/doc/api/session.md @@ -39,6 +39,7 @@ Example response: "twitter": "", "website_url": "", "email": "john@example.com", + "theme_id": 1, "color_scheme_id": 1, "projects_limit": 10, "current_sign_in_at": "2015-07-07T07:10:58.392Z", diff --git a/doc/api/users.md b/doc/api/users.md index 9f3e4caf2f4..6d5db16b36a 100644 --- a/doc/api/users.md +++ b/doc/api/users.md @@ -72,6 +72,7 @@ GET /users "organization": "", "last_sign_in_at": "2012-06-01T11:41:01Z", "confirmed_at": "2012-05-23T09:05:22Z", + "theme_id": 1, "last_activity_on": "2012-05-23", "color_scheme_id": 2, "projects_limit": 100, @@ -105,6 +106,7 @@ GET /users "organization": "", "last_sign_in_at": null, "confirmed_at": "2012-05-30T16:53:06.148Z", + "theme_id": 1, "last_activity_on": "2012-05-23", "color_scheme_id": 3, "projects_limit": 100, @@ -215,6 +217,7 @@ Parameters: "organization": "", "last_sign_in_at": "2012-06-01T11:41:01Z", "confirmed_at": "2012-05-23T09:05:22Z", + "theme_id": 1, "last_activity_on": "2012-05-23", "color_scheme_id": 2, "projects_limit": 100, @@ -341,6 +344,7 @@ GET /user "organization": "", "last_sign_in_at": "2012-06-01T11:41:01Z", "confirmed_at": "2012-05-23T09:05:22Z", + "theme_id": 1, "last_activity_on": "2012-05-23", "color_scheme_id": 2, "projects_limit": 100, @@ -387,6 +391,7 @@ GET /user "organization": "", "last_sign_in_at": "2012-06-01T11:41:01Z", "confirmed_at": "2012-05-23T09:05:22Z", + "theme_id": 1, "last_activity_on": "2012-05-23", "color_scheme_id": 2, "projects_limit": 100, -- cgit v1.2.1 From 2915bb27078a3eae0bac36bd2c3a2e1c4998130c Mon Sep 17 00:00:00 2001 From: blackst0ne Date: Thu, 7 Sep 2017 09:21:52 +1100 Subject: Add API support for wiki pages --- doc/api/README.md | 1 + doc/api/wikis.md | 157 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 158 insertions(+) create mode 100644 doc/api/wikis.md (limited to 'doc/api') diff --git a/doc/api/README.md b/doc/api/README.md index 266b5f018d9..f8e565ddbe5 100644 --- a/doc/api/README.md +++ b/doc/api/README.md @@ -58,6 +58,7 @@ following locations: - [Validate CI configuration](lint.md) - [V3 to V4](v3_to_v4.md) - [Version](version.md) +- [Wikis](wikis.md) ## Road to GraphQL diff --git a/doc/api/wikis.md b/doc/api/wikis.md new file mode 100644 index 00000000000..10eebc4a3c1 --- /dev/null +++ b/doc/api/wikis.md @@ -0,0 +1,157 @@ +# Wikis API + +> [Introduced][ce-13372] in GitLab 10.0. + +Available only in APIv4. + +## List wiki pages + +Get all wiki pages for a given project. + +``` +GET /projects/:id/wikis +``` + +| Attribute | Type | Required | Description | +| --------- | ------- | -------- | --------------------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `with_content` | boolean | no | Include pages' content | + +```bash +curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/1/wikis?with_content=1 +``` + +Example response: + +```json +[ + { + "content" : "Here is an instruction how to deploy this project.", + "format" : "markdown", + "slug" : "deploy", + "title" : "deploy" + }, + { + "content" : "Our development process is described here.", + "format" : "markdown", + "slug" : "development", + "title" : "development" + },{ + "content" : "* [Deploy](deploy)\n* [Development](development)", + "format" : "markdown", + "slug" : "home", + "title" : "home" + } +] +``` + +## Get a wiki page + +Get a wiki page for a given project. + +``` +GET /projects/:id/wikis/:slug +``` + +| Attribute | Type | Required | Description | +| --------- | ------- | -------- | --------------------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `slug` | string | yes | The slug (a unique string) of the wiki page | + +```bash +curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/1/wikis/home +``` + +Example response: + +```json +[ + { + "content" : "home page", + "format" : "markdown", + "slug" : "home", + "title" : "home" + } +] +``` + +## Create a new wiki page + +Creates a new wiki page for the given repository with the given title, slug, and content. + +``` +POST /projects/:id/wikis +``` + +| Attribute | Type | Required | Description | +| ------------- | ------- | -------- | ---------------------------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `content` | string | yes | The content of the wiki page | +| `title` | string | yes | The title of the wiki page | +| `format` | string | no | The format of the wiki page. Available formats are: `markdown` (default), `rdoc`, and `asciidoc` | + +```bash +curl --data "format=rdoc&title=Hello&content=Hello world" --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/1/wikis" +``` + +Example response: + +```json +{ + "content" : "Hello world", + "format" : "markdown", + "slug" : "Hello", + "title" : "Hello" +} +``` + +## Edit an existing wiki page + +Updates an existing wiki page. At least one parameter is required to update the wiki page. + +``` +PUT /projects/:id/wikis/:slug +``` + +| Attribute | Type | Required | Description | +| --------------- | ------- | --------------------------------- | ------------------------------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `content` | string | yes if `title` is not provided | The content of the wiki page | +| `title` | string | yes if `content` is not provided | The title of the wiki page | +| `format` | string | no | The format of the wiki page. Available formats are: `markdown` (default), `rdoc`, and `asciidoc` | +| `slug` | string | yes | The slug (a unique string) of the wiki page | + + +```bash +curl --request PUT --data "format=rdoc&content=documentation&title=Docs" --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/1/wikis/foo" +``` + +Example response: + +```json +{ + "content" : "documentation", + "format" : "markdown", + "slug" : "Docs", + "title" : "Docs" +} +``` + +## Delete a wiki page + +Deletes a wiki page with a given slug. + +``` +DELETE /projects/:id/wikis/:slug +``` + +| Attribute | Type | Required | Description | +| --------- | ------- | -------- | --------------------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `slug` | string | yes | The slug (a unique string) of the wiki page | + +```bash +curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/1/wikis/foo" +``` + +On success the HTTP status code is `204` and no JSON response is expected. -- cgit v1.2.1