From 60b3ea9493deae26ab83cadf1d868ee421fcfff5 Mon Sep 17 00:00:00 2001 From: Evan Read Date: Fri, 8 Feb 2019 13:57:31 +0000 Subject: Refactor snippets API documentation page --- doc/api/snippets.md | 216 ++++++++++++++++++++++++++++++++++----------------- doc/user/snippets.md | 7 +- 2 files changed, 152 insertions(+), 71 deletions(-) diff --git a/doc/api/snippets.md b/doc/api/snippets.md index 2cbd041d132..f90447e124e 100644 --- a/doc/api/snippets.md +++ b/doc/api/snippets.md @@ -1,43 +1,100 @@ # Snippets API -> [Introduced][ce-6373] in GitLab 8.15. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/6373) in GitLab 8.15. + +Snippets API operates on [snippets](../user/snippets.md). ## Snippet visibility level Snippets in GitLab can be either private, internal, or public. You can set it with the `visibility` field in the snippet. -Constants for snippet visibility levels are: +Valid values for snippet visibility levels are: -| Visibility | Description | -| ---------- | ----------- | -| `private` | The snippet is visible only to the snippet creator | -| `internal` | The snippet is visible for any logged in user | -| `public` | The snippet can be accessed without any authentication | +| Visibility | Description | +|:-----------|:----------------------------------------------------| +| `private` | Snippet is visible only to the snippet creator. | +| `internal` | Snippet is visible for any logged in user. | +| `public` | Snippet can be accessed without any authentication. | -## List snippets +## List all snippets for a user -Get a list of current user's snippets. +Get a list of the current user's snippets. -``` +```text GET /snippets ``` -## Single snippet +Example request: -Get a single snippet. +```sh +curl --header "PRIVATE-TOKEN: " https://gitlab.example.com/api/v4/snippets +``` + +Example response: +```json +[ + { + "id": 42, + "title": "Voluptatem iure ut qui aut et consequatur quaerat.", + "file_name": "mclaughlin.rb", + "description": null, + "visibility": "internal", + "author": { + "id": 22, + "name": "User 0", + "username": "user0", + "state": "active", + "avatar_url": "https://www.gravatar.com/avatar/52e4ce24a915fb7e51e1ad3b57f4b00a?s=80&d=identicon", + "web_url": "http://localhost:3000/user0" + }, + "updated_at": "2018-09-18T01:12:26.383Z", + "created_at": "2018-09-18T01:12:26.383Z", + "project_id": null, + "web_url": "http://localhost:3000/snippets/42", + "raw_url": "http://localhost:3000/snippets/42/raw" + }, + { + "id": 41, + "title": "Ut praesentium non et atque.", + "file_name": "ondrickaemard.rb", + "description": null, + "visibility": "internal", + "author": { + "id": 22, + "name": "User 0", + "username": "user0", + "state": "active", + "avatar_url": "https://www.gravatar.com/avatar/52e4ce24a915fb7e51e1ad3b57f4b00a?s=80&d=identicon", + "web_url": "http://localhost:3000/user0" + }, + "updated_at": "2018-09-18T01:12:26.360Z", + "created_at": "2018-09-18T01:12:26.360Z", + "project_id": null, + "web_url": "http://localhost:3000/snippets/41", + "raw_url": "http://localhost:3000/snippets/41/raw" + } +] ``` + +## Get a single snippet + +Get a single snippet. + +```text GET /snippets/:id ``` Parameters: -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | Integer | yes | The ID of a snippet | +| Attribute | Type | Required | Description | +|:----------|:--------|:---------|:---------------------------| +| `id` | integer | yes | ID of snippet to retrieve. | + +Example request: -```bash +```sh curl --header "PRIVATE-TOKEN: " https://gitlab.example.com/api/v4/snippets/1 ``` @@ -69,46 +126,52 @@ Example response: Get a single snippet's raw contents. -``` +```text GET /snippets/:id/raw ``` Parameters: -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | Integer | yes | The ID of a snippet | +| Attribute | Type | Required | Description | +|:----------|:--------|:---------|:---------------------------| +| `id` | integer | yes | ID of snippet to retrieve. | -```bash +Example request: + +```sh curl --header "PRIVATE-TOKEN: " https://gitlab.example.com/api/v4/snippets/1/raw ``` Example response: -``` +```text Hello World snippet ``` ## Create new snippet -Creates a new snippet. The user must have permission to create new snippets. +Create a new snippet. -``` +NOTE: **Note:** +The user must have permission to create new snippets. + +```text POST /snippets ``` Parameters: -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `title` | String | yes | The title of a snippet | -| `file_name` | String | yes | The name of a snippet file | -| `content` | String | yes | The content of a snippet | -| `description` | String | no | The description of a snippet | -| `visibility` | String | no | The snippet's visibility | +| Attribute | Type | Required | Description | +|:--------------|:-------|:---------|:---------------------------------------------------| +| `title` | string | yes | Title of a snippet. | +| `file_name` | string | yes | Name of a snippet file. | +| `content` | string | yes | Content of a snippet. | +| `description` | string | no | Description of a snippet. | +| `visibility` | string | no | Snippet's [visibility](#snippet-visibility-level). | +Example request: -```bash +```sh curl --request POST \ --data '{"title": "This is a snippet", "content": "Hello world", "description": "Hello World snippet", "file_name": "test.txt", "visibility": "internal" }' \ --header 'Content-Type: application/json' \ @@ -142,25 +205,29 @@ Example response: ## Update snippet -Updates an existing snippet. The user must have permission to change an existing snippet. +Update an existing snippet. -``` +NOTE: **Note:** +The user must have permission to change an existing snippet. + +```text PUT /snippets/:id ``` Parameters: -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | Integer | yes | The ID of a snippet | -| `title` | String | no | The title of a snippet | -| `file_name` | String | no | The name of a snippet file | -| `description` | String | no | The description of a snippet | -| `content` | String | no | The content of a snippet | -| `visibility` | String | no | The snippet's visibility | +| Attribute | Type | Required | Description | +|:--------------|:--------|:---------|:---------------------------------------------------| +| `id` | integer | yes | ID of snippet to update. | +| `title` | string | no | Title of a snippet. | +| `file_name` | string | no | Name of a snippet file. | +| `description` | string | no | Description of a snippet. | +| `content` | string | no | Content of a snippet. | +| `visibility` | string | no | Snippet's [visibility](#snippet-visibility-level). | +Example request: -```bash +```sh curl --request PUT \ --data '{"title": "foo", "content": "bar"}' \ --header 'Content-Type: application/json' \ @@ -194,38 +261,49 @@ Example response: ## Delete snippet -Deletes an existing snippet. +Delete an existing snippet. -``` +```text DELETE /snippets/:id ``` Parameters: -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | Integer | yes | The ID of a snippet | +| Attribute | Type | Required | Description | +|:----------|:--------|:---------|:-------------------------| +| `id` | integer | yes | ID of snippet to delete. | +Example request: -``` +```sh curl --request DELETE --header "PRIVATE-TOKEN: " "https://gitlab.example.com/api/v4/snippets/1" ``` -upon successful delete a `204 No content` HTTP code shall be expected, with no data, -but if the snippet is non-existent, a `404 Not Found` will be returned. +The following are possible return codes: -## Explore all public snippets +| Code | Description | +|:------|:--------------------------------------------| +| `204` | Delete was successful. No data is returned. | +| `404` | The snippet wasn't found. | -``` +## List all public snippets + +List all public snippets. + +```text GET /snippets/public ``` -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `per_page` | Integer | no | number of snippets to return per page | -| `page` | Integer | no | the page to retrieve | +Parameters: + +| Attribute | Type | Required | Description | +|:-----------|:--------|:---------|:---------------------------------------| +| `per_page` | integer | no | Number of snippets to return per page. | +| `page` | integer | no | Page to retrieve. | -```bash +Example request: + +```sh curl --header "PRIVATE-TOKEN: " https://gitlab.example.com/api/v4/snippets/public?per_page=2&page=1 ``` @@ -273,21 +351,22 @@ Example response: ## Get user agent details -> **Notes:** -> [Introduced][ce-29508] in GitLab 9.4. - +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/12655) in GitLab 9.4. -Available only for admins. +NOTE: **Note:** +Available only for administrators. -``` +```text GET /snippets/:id/user_agent_detail ``` -| Attribute | Type | Required | Description | -|-------------|---------|----------|--------------------------------------| -| `id` | Integer | yes | The ID of a snippet | +| Attribute | Type | Required | Description | +|:----------|:--------|:---------|:---------------| +| `id` | integer | yes | ID of snippet. | -```bash +Example request: + +```sh curl --request GET --header "PRIVATE-TOKEN: " https://gitlab.example.com/api/v4/snippets/1/user_agent_detail ``` @@ -300,6 +379,3 @@ Example response: "akismet_submitted": false } ``` - -[ce-6373]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/6373 -[ce-29508]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/12655 diff --git a/doc/user/snippets.md b/doc/user/snippets.md index 5c9f6ffb163..569bdc9e2d5 100644 --- a/doc/user/snippets.md +++ b/doc/user/snippets.md @@ -4,7 +4,12 @@ With GitLab Snippets you can store and share bits of code and text with other us ![GitLab Snippet](img/gitlab_snippet.png) -There are 2 types of snippets, personal snippets and project snippets. +Snippets can be maintained using [snippets API](../api/snippets.md). + +There are two types of snippets: + +- Personal snippets. +- Project snippets. ## Personal snippets -- cgit v1.2.1