Skip to content

Commit 60b3ea9

Browse files
ereadaxilleas
eread
authored and
axilleas
committed
Refactor snippets API documentation page
1 parent e04ca9a commit 60b3ea9

File tree

2 files changed

+152
-71
lines changed

2 files changed

+152
-71
lines changed

‎doc/api/snippets.md

+146-70
Original file line numberDiff line numberDiff line change
@@ -1,43 +1,100 @@
11
# Snippets API
22

3-
> [Introduced][ce-6373] in GitLab 8.15.
3+
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/6373) in GitLab 8.15.
4+
5+
Snippets API operates on [snippets](../user/snippets.md).
46

57
## Snippet visibility level
68

79
Snippets in GitLab can be either private, internal, or public.
810
You can set it with the `visibility` field in the snippet.
911

10-
Constants for snippet visibility levels are:
12+
Valid values for snippet visibility levels are:
1113

12-
| Visibility | Description |
13-
| ---------- | ----------- |
14-
| `private` | The snippet is visible only to the snippet creator |
15-
| `internal` | The snippet is visible for any logged in user |
16-
| `public` | The snippet can be accessed without any authentication |
14+
| Visibility | Description |
15+
|:-----------|:----------------------------------------------------|
16+
| `private` | Snippet is visible only to the snippet creator. |
17+
| `internal` | Snippet is visible for any logged in user. |
18+
| `public` | Snippet can be accessed without any authentication. |
1719

18-
## List snippets
20+
## List all snippets for a user
1921

20-
Get a list of current user's snippets.
22+
Get a list of the current user's snippets.
2123

22-
```
24+
```text
2325
GET /snippets
2426
```
2527

26-
## Single snippet
28+
Example request:
2729

28-
Get a single snippet.
30+
```sh
31+
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/snippets
32+
```
33+
34+
Example response:
2935

36+
```json
37+
[
38+
{
39+
"id": 42,
40+
"title": "Voluptatem iure ut qui aut et consequatur quaerat.",
41+
"file_name": "mclaughlin.rb",
42+
"description": null,
43+
"visibility": "internal",
44+
"author": {
45+
"id": 22,
46+
"name": "User 0",
47+
"username": "user0",
48+
"state": "active",
49+
"avatar_url": "https://www.gravatar.com/avatar/52e4ce24a915fb7e51e1ad3b57f4b00a?s=80&d=identicon",
50+
"web_url": "http://localhost:3000/user0"
51+
},
52+
"updated_at": "2018-09-18T01:12:26.383Z",
53+
"created_at": "2018-09-18T01:12:26.383Z",
54+
"project_id": null,
55+
"web_url": "http://localhost:3000/snippets/42",
56+
"raw_url": "http://localhost:3000/snippets/42/raw"
57+
},
58+
{
59+
"id": 41,
60+
"title": "Ut praesentium non et atque.",
61+
"file_name": "ondrickaemard.rb",
62+
"description": null,
63+
"visibility": "internal",
64+
"author": {
65+
"id": 22,
66+
"name": "User 0",
67+
"username": "user0",
68+
"state": "active",
69+
"avatar_url": "https://www.gravatar.com/avatar/52e4ce24a915fb7e51e1ad3b57f4b00a?s=80&d=identicon",
70+
"web_url": "http://localhost:3000/user0"
71+
},
72+
"updated_at": "2018-09-18T01:12:26.360Z",
73+
"created_at": "2018-09-18T01:12:26.360Z",
74+
"project_id": null,
75+
"web_url": "http://localhost:3000/snippets/41",
76+
"raw_url": "http://localhost:3000/snippets/41/raw"
77+
}
78+
]
3079
```
80+
81+
## Get a single snippet
82+
83+
Get a single snippet.
84+
85+
```text
3186
GET /snippets/:id
3287
```
3388

3489
Parameters:
3590

36-
| Attribute | Type | Required | Description |
37-
| --------- | ---- | -------- | ----------- |
38-
| `id` | Integer | yes | The ID of a snippet |
91+
| Attribute | Type | Required | Description |
92+
|:----------|:--------|:---------|:---------------------------|
93+
| `id` | integer | yes | ID of snippet to retrieve. |
94+
95+
Example request:
3996

40-
```bash
97+
```sh
4198
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/snippets/1
4299
```
43100

@@ -69,46 +126,52 @@ Example response:
69126

70127
Get a single snippet's raw contents.
71128

72-
```
129+
```text
73130
GET /snippets/:id/raw
74131
```
75132

76133
Parameters:
77134

78-
| Attribute | Type | Required | Description |
79-
| --------- | ---- | -------- | ----------- |
80-
| `id` | Integer | yes | The ID of a snippet |
135+
| Attribute | Type | Required | Description |
136+
|:----------|:--------|:---------|:---------------------------|
137+
| `id` | integer | yes | ID of snippet to retrieve. |
81138

82-
```bash
139+
Example request:
140+
141+
```sh
83142
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/snippets/1/raw
84143
```
85144

86145
Example response:
87146

88-
```
147+
```text
89148
Hello World snippet
90149
```
91150

92151
## Create new snippet
93152

94-
Creates a new snippet. The user must have permission to create new snippets.
153+
Create a new snippet.
95154

96-
```
155+
NOTE: **Note:**
156+
The user must have permission to create new snippets.
157+
158+
```text
97159
POST /snippets
98160
```
99161

100162
Parameters:
101163

102-
| Attribute | Type | Required | Description |
103-
| --------- | ---- | -------- | ----------- |
104-
| `title` | String | yes | The title of a snippet |
105-
| `file_name` | String | yes | The name of a snippet file |
106-
| `content` | String | yes | The content of a snippet |
107-
| `description` | String | no | The description of a snippet |
108-
| `visibility` | String | no | The snippet's visibility |
164+
| Attribute | Type | Required | Description |
165+
|:--------------|:-------|:---------|:---------------------------------------------------|
166+
| `title` | string | yes | Title of a snippet. |
167+
| `file_name` | string | yes | Name of a snippet file. |
168+
| `content` | string | yes | Content of a snippet. |
169+
| `description` | string | no | Description of a snippet. |
170+
| `visibility` | string | no | Snippet's [visibility](#snippet-visibility-level). |
109171

172+
Example request:
110173

111-
```bash
174+
```sh
112175
curl --request POST \
113176
--data '{"title": "This is a snippet", "content": "Hello world", "description": "Hello World snippet", "file_name": "test.txt", "visibility": "internal" }' \
114177
--header 'Content-Type: application/json' \
@@ -142,25 +205,29 @@ Example response:
142205

143206
## Update snippet
144207

145-
Updates an existing snippet. The user must have permission to change an existing snippet.
208+
Update an existing snippet.
146209

147-
```
210+
NOTE: **Note:**
211+
The user must have permission to change an existing snippet.
212+
213+
```text
148214
PUT /snippets/:id
149215
```
150216

151217
Parameters:
152218

153-
| Attribute | Type | Required | Description |
154-
| --------- | ---- | -------- | ----------- |
155-
| `id` | Integer | yes | The ID of a snippet |
156-
| `title` | String | no | The title of a snippet |
157-
| `file_name` | String | no | The name of a snippet file |
158-
| `description` | String | no | The description of a snippet |
159-
| `content` | String | no | The content of a snippet |
160-
| `visibility` | String | no | The snippet's visibility |
219+
| Attribute | Type | Required | Description |
220+
|:--------------|:--------|:---------|:---------------------------------------------------|
221+
| `id` | integer | yes | ID of snippet to update. |
222+
| `title` | string | no | Title of a snippet. |
223+
| `file_name` | string | no | Name of a snippet file. |
224+
| `description` | string | no | Description of a snippet. |
225+
| `content` | string | no | Content of a snippet. |
226+
| `visibility` | string | no | Snippet's [visibility](#snippet-visibility-level). |
161227

228+
Example request:
162229

163-
```bash
230+
```sh
164231
curl --request PUT \
165232
--data '{"title": "foo", "content": "bar"}' \
166233
--header 'Content-Type: application/json' \
@@ -194,38 +261,49 @@ Example response:
194261

195262
## Delete snippet
196263

197-
Deletes an existing snippet.
264+
Delete an existing snippet.
198265

199-
```
266+
```text
200267
DELETE /snippets/:id
201268
```
202269

203270
Parameters:
204271

205-
| Attribute | Type | Required | Description |
206-
| --------- | ---- | -------- | ----------- |
207-
| `id` | Integer | yes | The ID of a snippet |
272+
| Attribute | Type | Required | Description |
273+
|:----------|:--------|:---------|:-------------------------|
274+
| `id` | integer | yes | ID of snippet to delete. |
208275

276+
Example request:
209277

210-
```
278+
```sh
211279
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/snippets/1"
212280
```
213281

214-
upon successful delete a `204 No content` HTTP code shall be expected, with no data,
215-
but if the snippet is non-existent, a `404 Not Found` will be returned.
282+
The following are possible return codes:
216283

217-
## Explore all public snippets
284+
| Code | Description |
285+
|:------|:--------------------------------------------|
286+
| `204` | Delete was successful. No data is returned. |
287+
| `404` | The snippet wasn't found. |
218288

219-
```
289+
## List all public snippets
290+
291+
List all public snippets.
292+
293+
```text
220294
GET /snippets/public
221295
```
222296

223-
| Attribute | Type | Required | Description |
224-
| --------- | ---- | -------- | ----------- |
225-
| `per_page` | Integer | no | number of snippets to return per page |
226-
| `page` | Integer | no | the page to retrieve |
297+
Parameters:
298+
299+
| Attribute | Type | Required | Description |
300+
|:-----------|:--------|:---------|:---------------------------------------|
301+
| `per_page` | integer | no | Number of snippets to return per page. |
302+
| `page` | integer | no | Page to retrieve. |
227303

228-
```bash
304+
Example request:
305+
306+
```sh
229307
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/snippets/public?per_page=2&page=1
230308
```
231309

@@ -273,21 +351,22 @@ Example response:
273351

274352
## Get user agent details
275353

276-
> **Notes:**
277-
> [Introduced][ce-29508] in GitLab 9.4.
278-
354+
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/12655) in GitLab 9.4.
279355
280-
Available only for admins.
356+
NOTE: **Note:**
357+
Available only for administrators.
281358

282-
```
359+
```text
283360
GET /snippets/:id/user_agent_detail
284361
```
285362

286-
| Attribute | Type | Required | Description |
287-
|-------------|---------|----------|--------------------------------------|
288-
| `id` | Integer | yes | The ID of a snippet |
363+
| Attribute | Type | Required | Description |
364+
|:----------|:--------|:---------|:---------------|
365+
| `id` | integer | yes | ID of snippet. |
289366

290-
```bash
367+
Example request:
368+
369+
```sh
291370
curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/snippets/1/user_agent_detail
292371
```
293372

@@ -300,6 +379,3 @@ Example response:
300379
"akismet_submitted": false
301380
}
302381
```
303-
304-
[ce-6373]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/6373
305-
[ce-29508]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/12655

‎doc/user/snippets.md

+6-1
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,12 @@ With GitLab Snippets you can store and share bits of code and text with other us
44

55
![GitLab Snippet](img/gitlab_snippet.png)
66

7-
There are 2 types of snippets, personal snippets and project snippets.
7+
Snippets can be maintained using [snippets API](../api/snippets.md).
8+
9+
There are two types of snippets:
10+
11+
- Personal snippets.
12+
- Project snippets.
813

914
## Personal snippets
1015

0 commit comments

Comments
 (0)