diff options
Diffstat (limited to 'doc/api/snippets.md')
| -rw-r--r-- | doc/api/snippets.md | 105 |
1 files changed, 80 insertions, 25 deletions
diff --git a/doc/api/snippets.md b/doc/api/snippets.md index 6863763ff24..431d745ac84 100644 --- a/doc/api/snippets.md +++ b/doc/api/snippets.md @@ -198,22 +198,40 @@ POST /snippets Parameters: -| 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). | +| Attribute | Type | Required | Description | +|:------------------|:----------------|:---------|:--------------------------------------------------------| +| `title` | string | yes | Title of a snippet | +| `file_name` | string | no | Deprecated: Use `files` instead. Name of a snippet file | +| `content` | string | no | Deprecated: Use `files` instead. Content of a snippet | +| `description` | string | no | Description of a snippet | +| `visibility` | string | no | Snippet's [visibility](#snippet-visibility-level) | +| `files` | array of hashes | no | An array of snippet files | +| `files:file_path` | string | yes | File path of the snippet file | +| `files:content` | string | yes | Content of the snippet file | Example request: ```shell -curl --request POST \ - --data '{"title": "This is a snippet", "content": "Hello world", "description": "Hello World snippet", "file_name": "test.txt", "visibility": "internal" }' \ +curl --request POST "https://gitlab.example.com/api/v4/snippets" \ --header 'Content-Type: application/json' \ --header "PRIVATE-TOKEN: <your_access_token>" \ - "https://gitlab.example.com/api/v4/snippets" + -d @snippet.json +``` + +`snippet.json` used in the above example request: + +```json +{ + "title": "This is a snippet", + "description": "Hello World snippet", + "visibility": "internal", + "files": [ + { + "content": "Hello world", + "file_path": "test.txt" + } + ] +} ``` Example response: @@ -222,7 +240,6 @@ Example response: { "id": 1, "title": "This is a snippet", - "file_name": "test.txt", "description": "Hello World snippet", "visibility": "internal", "author": { @@ -238,7 +255,16 @@ Example response: "created_at": "2012-06-28T10:52:04Z", "project_id": null, "web_url": "http://example.com/snippets/1", - "raw_url": "http://example.com/snippets/1/raw" + "raw_url": "http://example.com/snippets/1/raw", + "ssh_url_to_repo": "ssh://git@gitlab.example.com:snippets/1.git", + "http_url_to_repo": "https://gitlab.example.com/snippets/1.git", + "file_name": "test.txt", + "files": [ + { + "path": "text.txt", + "raw_url": "https://gitlab.example.com/-/snippets/1/raw/master/renamed.md" + } + ] } ``` @@ -255,23 +281,44 @@ PUT /snippets/:id Parameters: -| 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). | +| Attribute | Type | Required | Description | +|:----------------------|:----------------|:---------|:------------------------------------------------------------------------------------| +| `id` | integer | yes | ID of snippet to update | +| `title` | string | no | Title of a snippet | +| `file_name` | string | no | Deprecated: Use `files` instead. Name of a snippet file | +| `content` | string | no | Deprecated: Use `files` instead. Content of a snippet | +| `description` | string | no | Description of a snippet | +| `visibility` | string | no | Snippet's [visibility](#snippet-visibility-level) | +| `files` | array of hashes | no | An array of snippet files | +| `files:action` | string | yes | Type of action to perform on the file, one of: 'create', 'update', 'delete', 'move' | +| `files:file_path` | string | no | File path of the snippet file | +| `files:previous_path` | string | no | Previous path of the snippet file | +| `files:content` | string | no | Content of the snippet file | + +Updates to snippets with multiple files *must* use the `files` attribute. Example request: ```shell -curl --request PUT \ - --data '{"title": "foo", "content": "bar"}' \ +curl --request PUT "https://gitlab.example.com/api/v4/snippets/1" \ --header 'Content-Type: application/json' \ --header "PRIVATE-TOKEN: <your_access_token>" \ - "https://gitlab.example.com/api/v4/snippets/1" + -d @snippet.json +``` + +`snippet.json` used in the above example request: + +```json +{ + "title": "foo", + "files": [ + { + "action": "move", + "previous_path": "test.txt", + "file_path": "renamed.md" + } + ] +} ``` Example response: @@ -280,7 +327,6 @@ Example response: { "id": 1, "title": "test", - "file_name": "add.rb", "description": "description of snippet", "visibility": "internal", "author": { @@ -296,7 +342,16 @@ Example response: "created_at": "2012-06-28T10:52:04Z", "project_id": null, "web_url": "http://example.com/snippets/1", - "raw_url": "http://example.com/snippets/1/raw" + "raw_url": "http://example.com/snippets/1/raw", + "ssh_url_to_repo": "ssh://git@gitlab.example.com:snippets/1.git", + "http_url_to_repo": "https://gitlab.example.com/snippets/1.git", + "file_name": "renamed.md", + "files": [ + { + "path": "renamed.md", + "raw_url": "https://gitlab.example.com/-/snippets/1/raw/master/renamed.md" + } + ] } ``` |