Merge branch 'docs-release-asset-link' into 'master'

Add documentation for Release Asset Link API

Closes #56060

See merge request gitlab-org/gitlab-ce!24211

doc/api/README.md

@@ -69,6 +69,9 @@ The following API resources are available:
 - [Sidekiq metrics](sidekiq_metrics.md)
 - [System hooks](system_hooks.md)
 - [Tags](tags.md)
+- [Releases](releases/index.md)
+- Release Assets
+  - [Links](releases/links.md)
 - [Todos](todos.md)
 - [Users](users.md)
 - [Validate CI configuration](lint.md) (linting)

doc/api/releases.md → doc/api/releases/index.md

 # Releases API
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/41766) in GitLab 11.7.
-> - Using this API you can manipulate GitLab's [Release](../user/project/releases/index.md) entries.
+> - Using this API you can manipulate GitLab's [Release](../../user/project/releases/index.md) entries.
+> - For manipulating links as a release asset, see [Release Links API](links.md)
 ## List Releases
@@ -241,7 +242,7 @@ POST /projects/:id/releases
 | `id`          | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). |
 | `name`        | string         | yes      | The release name.                       |
 | `tag_name`    | string         | yes      | The tag where the release will be created from. |
-| `description` | string         | no       | The description of the release. You can use [markdown](../user/markdown.md). |
+| `description` | string         | yes      | The description of the release. You can use [markdown](../user/markdown.md). |
 | `ref`         | string         | no       | If `tag_name` doesn't exist, the release will be created from `ref`. It can be a commit SHA, another tag name, or a branch name. |
 | `assets:links`| array of hash  | no       | An array of assets links.               |
 | `assets:links:name`| string    | no (if `assets:links` specified, it's required)    | The name of the link. |
@@ -331,8 +332,8 @@ PUT /projects/:id/releases/:tag_name
 | Attribute     | Type           | Required | Description                             |
 | ------------- | -------------- | -------- | --------------------------------------- |
 | `id`          | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). |
+| `tag_name`    | string         | yes      | The tag where the release will be created from. |
 | `name`        | string         | no       | The release name.                       |
-| `tag_name`    | string         | no       | The tag where the release will be created from. |
 | `description` | string         | no       | The description of the release. You can use [markdown](../user/markdown.md). |
 Example request:

doc/api/releases/links.md

+# Release links API
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/41766) in GitLab 11.7.
+
+Using this API you can manipulate GitLab's [Release](../../user/project/releases/index.md) links. For manipulating other Release assets, see [Release API](index.md).
+
+## Get links
+
+Get assets as links from a Release.
+
+```
+GET /projects/:id/releases/:tag_name/assets/links
+```
+
+| Attribute     | Type           | Required | Description                             |
+| ------------- | -------------- | -------- | --------------------------------------- |
+| `id`          | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). |
+| `tag_name`    | string         | yes      | The tag associated with the Release. |
+
+Example request:
+
+```sh
+curl --header "PRIVATE-TOKEN: gDybLx3yrUK_HLp3qPjS" "http://localhost:3000/api/v4/projects/24/releases/v0.1/assets/links"
+```
+
+Example response:
+
+```json
+[
+   {
+      "id":2,
+      "name":"awesome-v0.2.msi",
+      "url":"http://192.168.10.15:3000/msi",
+      "external":true
+   },
+   {
+      "id":1,
+      "name":"awesome-v0.2.dmg",
+      "url":"http://192.168.10.15:3000",
+      "external":true
+   }
+]
+```
+
+## Get a link
+
+Get an asset as a link from a Release.
+
+```
+GET /projects/:id/releases/:tag_name/assets/links/:link_id
+```
+
+| Attribute     | Type           | Required | Description                             |
+| ------------- | -------------- | -------- | --------------------------------------- |
+| `id`          | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). |
+| `tag_name`    | string         | yes      | The tag associated with the Release. |
+| `link_id`    | integer         | yes      | The id of the link. |
+
+Example request:
+
+```sh
+curl --header "PRIVATE-TOKEN: gDybLx3yrUK_HLp3qPjS" "http://localhost:3000/api/v4/projects/24/releases/v0.1/assets/links/1"
+```
+
+Example response:
+
+```json
+{
+   "id":1,
+   "name":"awesome-v0.2.dmg",
+   "url":"http://192.168.10.15:3000",
+   "external":true
+}
+```
+
+## Create a link
+
+Create an asset as a link from a Release.
+
+```
+POST /projects/:id/releases/:tag_name/assets/links
+```
+
+| Attribute     | Type           | Required | Description                             |
+| ------------- | -------------- | -------- | --------------------------------------- |
+| `id`          | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). |
+| `tag_name`    | string         | yes      | The tag associated with the Release. |
+| `name`        | string         | yes      | The name of the link. |
+| `url`        | string         | yes      | The URL of the link. |
+
+Example request:
+
+```sh
+curl --request POST \
+     --header "PRIVATE-TOKEN: gDybLx3yrUK_HLp3qPjS" \
+     --data name="awesome-v0.2.dmg" \
+     --data url="http://192.168.10.15:3000" \
+     "http://localhost:3000/api/v4/projects/24/releases/v0.1/assets/links"
+```
+
+Example response:
+
+```json
+{
+   "id":1,
+   "name":"awesome-v0.2.dmg",
+   "url":"http://192.168.10.15:3000",
+   "external":true
+}
+```
+
+## Update a link
+
+Update an asset as a link from a Release.
+
+```
+PUT /projects/:id/releases/:tag_name/assets/links/:link_id
+```
+
+| Attribute     | Type           | Required | Description                             |
+| ------------- | -------------- | -------- | --------------------------------------- |
+| `id`          | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). |
+| `tag_name`    | string         | yes      | The tag associated with the Release. |
+| `link_id`    | integer         | yes      | The id of the link. |
+| `name`        | string         | no | The name of the link. |
+| `url`        | string         | no | The URL of the link. |
+
+NOTE: **NOTE**
+You have to specify at least one of `name` or `url`
+
+Example request:
+
+```sh
+curl --request PUT --data name="new name" --header "PRIVATE-TOKEN: gDybLx3yrUK_HLp3qPjS" "http://localhost:3000/api/v4/projects/24/releases/v0.1/assets/links/1"
+```
+
+Example response:
+
+```json
+{
+   "id":1,
+   "name":"new name",
+   "url":"http://192.168.10.15:3000",
+   "external":true
+}
+```
+
+## Delete a link
+
+Delete an asset as a link from a Release.
+
+```
+DELETE /projects/:id/releases/:tag_name/assets/links/:link_id
+```
+
+| Attribute     | Type           | Required | Description                             |
+| ------------- | -------------- | -------- | --------------------------------------- |
+| `id`          | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). |
+| `tag_name`    | string         | yes      | The tag associated with the Release. |
+| `link_id`    | integer         | yes      | The id of the link. |
+
+Example request:
+
+```sh
+curl --request DELETE --header "PRIVATE-TOKEN: gDybLx3yrUK_HLp3qPjS" "http://localhost:3000/api/v4/projects/24/releases/v0.1/assets/links/1"
+```
+
+Example response:
+
+```json
+{
+   "id":1,
+   "name":"new name",
+   "url":"http://192.168.10.15:3000",
+   "external":true
+}
+```

doc/user/project/releases/index.md

@@ -12,7 +12,7 @@ GitLab's **Releases** are a way to track deliverables in your project. Consider
 a snapshot in time of the source, build output, and other metadata or artifacts
 associated with a released version of your code.
-At the moment, you can create Release entries via the [Releases API](../../../api/releases.md);
+At the moment, you can create Release entries via the [Releases API](../../../api/releases/index.md);
 we recommend doing this as one of the last steps in your CI/CD release pipeline.
 ## Getting started with Releases
@@ -51,6 +51,9 @@ A link is any URL which can point to whatever you like; documentation, built
 binaries, or other related materials. These can be both internal or external
 links from your GitLab instance.
+NOTE: **NOTE**
+You can manipulate links of each release entry with [Release Links API](../../../api/releases/links.md)
+
 ## Releases list
 Navigate to **Project > Releases** in order to see the list of releases for a given