BigW Consortium Gitlab

project_snippets.md 4.04 KB
Newer Older
1 2
# Project snippets

3 4 5
### Snippet visibility level

Snippets in GitLab can be either private, internal or public.
6
You can set it with the `visibility` field in the snippet.
7 8 9

Constants for snippet visibility levels are:

10 11 12 13 14
| visibility | Description |
| ---------- | ----------- |
| `private`  | The snippet is visible only the snippet creator |
| `internal` | The snippet is visible for any logged in user |
| `public`   | The snippet can be accessed without any authentication |
15

16 17
## List snippets

18 19 20 21 22 23 24 25
Get a list of project snippets.

```
GET /projects/:id/snippets
```

Parameters:

26
- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user
27

28 29
## Single snippet

30
Get a single project snippet.
31 32 33 34 35 36 37

```
GET /projects/:id/snippets/:snippet_id
```

Parameters:

38
- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user
39
- `snippet_id` (required) - The ID of a project's snippet
40 41 42 43 44 45

```json
{
  "id": 1,
  "title": "test",
  "file_name": "add.rb",
46
  "description": "Ruby test snippet",
47 48
  "author": {
    "id": 1,
49
    "username": "john_smith",
50 51
    "email": "john@example.com",
    "name": "John Smith",
52
    "state": "active",
53 54 55
    "created_at": "2012-05-23T08:00:58Z"
  },
  "updated_at": "2012-06-28T10:52:04Z",
56 57
  "created_at": "2012-06-28T10:52:04Z",
  "web_url": "http://example.com/example/example/snippets/1"
58 59 60
}
```

61
## Create new snippet
62

63
Creates a new project snippet. The user must have permission to create new snippets.
64 65 66 67 68 69 70

```
POST /projects/:id/snippets
```

Parameters:

71
- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user
72 73
- `title` (required) - The title of a snippet
- `file_name` (required) - The name of a snippet file
74
- `description` (optional) - The description of a snippet
75
- `code` (required) - The content of a snippet
76
- `visibility` (required) - The snippet's visibility
77

78
## Update snippet
79

80
Updates an existing project snippet. The user must have permission to change an existing snippet.
81 82 83 84 85 86 87

```
PUT /projects/:id/snippets/:snippet_id
```

Parameters:

88
- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user
89 90 91
- `snippet_id` (required) - The ID of a project's snippet
- `title` (optional) - The title of a snippet
- `file_name` (optional) - The name of a snippet file
92
- `description` (optional) - The description of a snippet
93
- `code` (optional) - The content of a snippet
94
- `visibility` (optional) - The snippet's visibility
95 96 97

## Delete snippet

98
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.
99 100 101 102 103 104 105

```
DELETE /projects/:id/snippets/:snippet_id
```

Parameters:

106
- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user
107
- `snippet_id` (required) - The ID of a project's snippet
108 109 110

## Snippet content

111
Returns the raw project snippet as plain text.
112 113 114 115 116 117 118

```
GET /projects/:id/snippets/:snippet_id/raw
```

Parameters:

119
- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user
120
- `snippet_id` (required) - The ID of a project's snippet
James Lopez committed
121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150

## Get user agent details

> **Notes:**
> [Introduced][ce-29508] in GitLab 9.4.


Available only for admins.

```
GET /projects/:id/snippets/:snippet_id/user_agent_detail
```

| Attribute   | Type    | Required | Description                          |
|-------------|---------|----------|--------------------------------------|
| `id`        | Integer | yes      | The ID of a snippet                  |

```bash
curl --request GET --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/1/snippets/1/user_agent_detail
```

Example response:

```json
{
  "user_agent": "AppleWebKit/537.36",
  "ip_address": "127.0.0.1",
  "akismet_submitted": false
}
```
151

152
[ce-29508]: https://gitlab.com/gitlab-org/gitlab-ce/issues/29508