Add latest changes from gitlab-org/gitlab@master

2 files changed, 625 insertions, 0 deletions

diff --git a/doc/api/packages/composer.md b/doc/api/packages/composer.md
new file mode 100644
index 00000000000..ebf3ffba92f
--- /dev/null
+++ b/doc/api/packages/composer.md
@@ -0,0 +1,287 @@
+---
+stage: Package
+group: Package
+info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
+---
+
+# Composer API
+
+This is the API documentation for [Composer Packages](../../user/packages/composer_repository/index.md).
+
+WARNING:
+This API is used by the [Composer package manager client](https://getcomposer.org/)
+and is generally not meant for manual consumption.
+
+For instructions on how to upload and install Composer packages from the GitLab
+package registry, see the [Composer package registry documentation](../../user/packages/composer_repository/index.md).
+
+NOTE:
+These endpoints do not adhere to the standard API authentication methods.
+See the [Composer package registry documentation](../../user/packages/composer_repository/index.md)
+for details on which headers and token types are supported.
+
+## Base repository request
+
+Returns the repository URL templates for requesting individual packages:
+
+```plaintext
+GET group/:id/-/packages/composer/packages
+```
+
+| Attribute | Type   | Required | Description |
+| --------- | ------ | -------- | ----------- |
+| `id`      | string | yes      | The ID or full path of the group. |
+
+```shell
+curl --user <username>:<personal_access_token> "https://gitlab.example.com/api/v4/group/1/-/packages/composer/packages"
+```
+
+Example response:
+
+```json
+{
+  "packages": [],
+  "metadata-url": "/api/v4/group/1/-/packages/composer/p2/%package%.json",
+  "provider-includes": {
+    "p/%hash%.json": {
+      "sha256": "082df4a5035f8725a12i4a3d2da5e6aaa966d06843d0a5c6d499313810427bd6"
+    }
+  },
+  "providers-url": "/api/v4/group/1/-/packages/composer/%package%$%hash%.json"
+}
+```
+
+This endpoint is used by Composer V1 and V2. To see the V2-specific response, include the Composer
+`User-Agent` header. Using Composer V2 is recommended over V1.
+
+```shell
+curl --user <username>:<personal_access_token> \
+     --header "User-Agent: Composer/2" \
+     "https://gitlab.example.com/api/v4/group/1/-/packages/composer/packages"
+```
+
+Example response:
+
+```json
+{
+  "packages": [],
+  "metadata-url": "/api/v4/group/1/-/packages/composer/p2/%package%.json"
+}
+```
+
+## V1 packages list
+
+Given the V1 provider sha, returns a list of packages within the repository. Using Composer V2 is
+recommended over V1.
+
+```plaintext
+GET group/:id/-/packages/composer/p/:sha
+```
+
+| Attribute | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `id`      | string | yes | The ID or full path of the group. |
+| `sha`     | string | yes | The provider sha, provided by the Composer [base request](#base-repository-request). |
+
+```shell
+curl --user <username>:<personal_access_token> "https://gitlab.example.com/api/v4/group/1/-/packages/composer/p/082df4a5035f8725a12i4a3d2da5e6aaa966d06843d0a5c6d499313810427bd6"
+```
+
+Example response:
+
+```json
+{
+  "providers": {
+    "my-org/my-composer-package": {
+      "sha256": "5c873497cdaa82eda35af5de24b789be92dfb6510baf117c42f03899c166b6e7"
+    }
+  }
+}
+```
+
+## V1 Package Metadata
+
+Returns the list of versions and metadata for a given package. Using Composer V2 is recommended over
+V1.
+
+```plaintext
+GET group/:id/-/packages/composer/:package_name$:sha
+```
+
+Note the `$` symbol in the URL. When making requests, you may need to use the URL-encoded version of
+the symbol `%24` (see example below).
+
+| Attribute      | Type   | Required | Description |
+| -------------- | ------ | -------- | ----------- |
+| `id`           | string | yes      | The ID or full path of the group. |
+| `package_name` | string | yes      | The name of the package. |
+| `sha`          | string | yes      | The sha digest of the package, provided by the [V1 packages list](#v1-packages-list). |
+
+```shell
+curl --user <username>:<personal_access_token> "https://gitlab.example.com/api/v4/group/1/-/packages/composer/my-org/my-composer-package%245c873497cdaa82eda35af5de24b789be92dfb6510baf117c42f03899c166b6e7"
+```
+
+Example response:
+
+```json
+{
+  "packages": {
+    "my-org/my-composer-package": {
+      "1.0.0": {
+        "name": "my-org/my-composer-package",
+        "type": "library",
+        "license": "GPL-3.0-only",
+        "version": "1.0.0",
+        "dist": {
+          "type": "zip",
+          "url": "https://gitlab.example.com/api/v4/projects/1/packages/composer/archives/my-org/my-composer-package.zip?sha=673594f85a55fe3c0eb45df7bd2fa9d95a1601ab",
+          "reference": "673594f85a55fe3c0eb45df7bd2fa9d95a1601ab",
+          "shasum": ""
+        },
+        "source": {
+          "type": "git",
+          "url": "https://gitlab.example.com/my-org/my-composer-package.git",
+          "reference": "673594f85a55fe3c0eb45df7bd2fa9d95a1601ab"
+        },
+        "uid": 1234567
+      },
+      "2.0.0": {
+        "name": "my-org/my-composer-package",
+        "type": "library",
+        "license": "GPL-3.0-only",
+        "version": "2.0.0",
+        "dist": {
+          "type": "zip",
+          "url": "https://gitlab.example.com/api/v4/projects/1/packages/composer/archives/my-org/my-composer-package.zip?sha=445394f85a55fe3c0eb45df7bd2fa9d95a1601ab",
+          "reference": "445394f85a55fe3c0eb45df7bd2fa9d95a1601ab",
+          "shasum": ""
+        },
+        "source": {
+          "type": "git",
+          "url": "https://gitlab.example.com/my-org/my-composer-package.git",
+          "reference": "445394f85a55fe3c0eb45df7bd2fa9d95a1601ab"
+        },
+        "uid": 1234567
+      }
+    }
+  }
+}
+```
+
+## V2 Package Metadata
+
+Returns the list of versions and metadata for a given package:
+
+```plaintext
+GET group/:id/-/packages/composer/p2/:package_name
+```
+
+| Attribute      | Type   | Required | Description |
+| -------------- | ------ | -------- | ----------- |
+| `id`           | string | yes      | The ID or full path of the group. |
+| `package_name` | string | yes      | The name of the package. |
+
+```shell
+curl --user <username>:<personal_access_token> "https://gitlab.example.com/api/v4/group/1/-/packages/composer/p2/my-org/my-composer-package"
+```
+
+Example response:
+
+```json
+{
+  "packages": {
+    "my-org/my-composer-package": {
+      "1.0.0": {
+        "name": "my-org/my-composer-package",
+        "type": "library",
+        "license": "GPL-3.0-only",
+        "version": "1.0.0",
+        "dist": {
+          "type": "zip",
+          "url": "https://gitlab.example.com/api/v4/projects/1/packages/composer/archives/my-org/my-composer-package.zip?sha=673594f85a55fe3c0eb45df7bd2fa9d95a1601ab",
+          "reference": "673594f85a55fe3c0eb45df7bd2fa9d95a1601ab",
+          "shasum": ""
+        },
+        "source": {
+          "type": "git",
+          "url": "https://gitlab.example.com/my-org/my-composer-package.git",
+          "reference": "673594f85a55fe3c0eb45df7bd2fa9d95a1601ab"
+        },
+        "uid": 1234567
+      },
+      "2.0.0": {
+        "name": "my-org/my-composer-package",
+        "type": "library",
+        "license": "GPL-3.0-only",
+        "version": "2.0.0",
+        "dist": {
+          "type": "zip",
+          "url": "https://gitlab.example.com/api/v4/projects/1/packages/composer/archives/my-org/my-composer-package.zip?sha=445394f85a55fe3c0eb45df7bd2fa9d95a1601ab",
+          "reference": "445394f85a55fe3c0eb45df7bd2fa9d95a1601ab",
+          "shasum": ""
+        },
+        "source": {
+          "type": "git",
+          "url": "https://gitlab.example.com/my-org/my-composer-package.git",
+          "reference": "445394f85a55fe3c0eb45df7bd2fa9d95a1601ab"
+        },
+        "uid": 1234567
+      }
+    }
+  }
+}
+```
+
+## Create a package
+
+Create a Composer package from a Git tag or branch:
+
+```plaintext
+POST projects/:id/packages/composer
+```
+
+| Attribute | Type   | Required | Description |
+| --------- | ------ | -------- | ----------- |
+| `id`      | string | yes      | The ID or full path of the group. |
+| `tag`     | string | no       | The name of the tag to target for the package. |
+| `branch`  | string | no       | The name of the branch to target for the package. |
+
+```shell
+curl --request POST --user <username>:<personal_access_token> --data tag=v1.0.0 "https://gitlab.example.com/api/v4/projects/1/packages/composer"
+```
+
+Example response:
+
+```json
+{
+  "message": "201 Created"
+}
+```
+
+## Download a package archive
+
+Download a Composer package. This URL is provided in the [v1](#v1-package-metadata)
+or [v2 package metadata](#v2-package-metadata)
+response. A `.zip` file extension must be in the request.
+
+```plaintext
+GET projects/:id/packages/composer/archives/:package_name
+```
+
+| Attribute      | Type   | Required | Description |
+| -------------- | ------ | -------- | ----------- |
+| `id`           | string | yes      | The ID or full path of the group. |
+| `package_name` | string | yes      | The name of the package. |
+| `sha`          | string | yes      | The target sha of the requested package version. |
+
+```shell
+curl --user <username>:<personal_access_token> "https://gitlab.example.com/api/v4/projects/1/packages/composer/archives/my-org/my-composer-package.zip?sha=673594f85a55fe3c0eb45df7bd2fa9d95a1601ab"
+```
+
+Write the output to file:
+
+```shell
+curl --user <username>:<personal_access_token> "https://gitlab.example.com/api/v4/projects/1/packages/composer/archives/my-org/my-composer-package.zip?sha=673594f85a55fe3c0eb45df7bd2fa9d95a1601ab" >> package.tar.gz
+```
+
+This writes the downloaded file to `package.tar.gz` in the current directory.
diff --git a/doc/api/packages/nuget.md b/doc/api/packages/nuget.md
new file mode 100644
index 00000000000..ed61704770b
--- /dev/null
+++ b/doc/api/packages/nuget.md
@@ -0,0 +1,338 @@
+---
+stage: Package
+group: Package
+info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about..example/handbook/engineering/ux/technical-writing/#assignments
+---
+
+# NuGet API
+
+This is the API documentation for [NuGet Packages](../../user/packages/nuget_repository/index.md).
+
+WARNING:
+This API is used by the [NuGet package manager client](https://www.nuget.org/)
+and is generally not meant for manual consumption.
+
+For instructions on how to upload and install NuGet packages from the GitLab
+package registry, see the [NuGet package registry documentation](../../user/packages/nuget_repository/index.md).
+
+NOTE:
+These endpoints do not adhere to the standard API authentication methods.
+See the [NuGet package registry documentation](../../user/packages/nuget_repository/index.md)
+for details on which headers and token types are supported.
+
+## Package index
+
+> Introduced in GitLab 12.8.
+
+Returns the index for a given package, which includes a list of available versions:
+
+```plaintext
+GET projects/:id/packages/nuget/download/:package_name/index
+```
+
+| Attribute      | Type   | Required | Description |
+| -------------- | ------ | -------- | ----------- |
+| `id`           | string | yes      | The ID or full path of the project. |
+| `package_name` | string | yes      | The name of the package. |
+
+```shell
+curl --user <username>:<personal_access_token> "https://gitlab.example.com/api/v4/projects/1/packages/nuget/download/MyNuGetPkg/index"
+```
+
+Example response:
+
+```json
+{
+  "versions": [
+    "1.3.0.17"
+  ]
+}
+```
+
+## Download a package file
+
+> Introduced in GitLab 12.8.
+
+Download a NuGet package file. The [metadata service](#metadata-service) provides this URL.
+
+```plaintext
+GET projects/:id/packages/nuget/download/:package_name/:package_version/:package_filename
+```
+
+| Attribute         | Type   | Required | Description |
+| ----------------- | ------ | -------- | ----------- |
+| `id`              | string | yes      | The ID or full path of the project. |
+| `package_name`    | string | yes      | The name of the package. |
+| `package_version` | string | yes      | The version of the package. |
+| `package_filename`| string | yes      | The name of the file. |
+
+```shell
+curl --user <username>:<personal_access_token> "https://gitlab.example.com/api/v4/projects/1/packages/nuget/download/MyNuGetPkg/1.3.0.17/mynugetpkg.1.3.0.17.nupkg"
+```
+
+Write the output to a file:
+
+```shell
+curl --user <username>:<personal_access_token> "https://gitlab.example.com/api/v4/projects/1/packages/nuget/download/MyNuGetPkg/1.3.0.17/mynugetpkg.1.3.0.17.nupkg" >> MyNuGetPkg.1.3.0.17.nupkg
+```
+
+This writes the downloaded file to `MyNuGetPkg.1.3.0.17.nupkg` in the current directory.
+
+## Upload a package file
+
+> Introduced in GitLab 12.8.
+
+Download a NuGet package file:
+
+```plaintext
+PUT projects/:id/packages/nuget
+```
+
+| Attribute         | Type   | Required | Description |
+| ----------------- | ------ | -------- | ----------- |
+| `id`              | string | yes      | The ID or full path of the project. |
+| `package_name`    | string | yes      | The name of the package. |
+| `package_version` | string | yes      | The version of the package. |
+| `package_filename`| string | yes      | The name of the file. |
+
+```shell
+curl --request PUT \
+     --upload-file path/to/mynugetpkg.1.3.0.17.nupkg \
+     --user <username>:<personal_access_token> \
+     "https://gitlab.example.com/api/v4/projects/1/packages/nuget"
+```
+
+## Route prefix
+
+For the remaining routes, there are two sets of identical routes that each make requests in
+different scopes:
+
+- Use the group-level prefix to make requests in a group's scope.
+- Use the project-level prefix to make requests in a single project's scope.
+
+The examples in this document all use the project-level prefix.
+
+### Group-level
+
+```plaintext
+ /groups/:id/-/packages/nuget`
+```
+
+| Attribute | Type   | Required | Description |
+| --------- | ------ | -------- | ----------- |
+| `id`      | string | yes      | The group ID or full group path. |
+
+### Project-level
+
+```plaintext
+ /projects/:id/packages/nuget`
+```
+
+| Attribute | Type   | Required | Description |
+| --------- | ------ | -------- | ----------- |
+| `id`      | string | yes      | The project ID or full project path. |
+
+## Service Index
+
+> Introduced in GitLab 12.6.
+
+Returns a list of available API resources:
+
+```plaintext
+GET <route-prefix>/index
+```
+
+Example Request:
+
+```shell
+curl --user <username>:<personal_access_token> "https://gitlab.example.com/api/v4/projects/1/packages/nuget/index"
+```
+
+Example response:
+
+```json
+{
+  "version": "3.0.0",
+  "resources": [
+    {
+      "@id": "https://gitlab.example.com/api/v4/projects/1/packages/nuget/query",
+      "@type": "SearchQueryService",
+      "comment": "Filter and search for packages by keyword."
+    },
+    {
+      "@id": "https://gitlab.example.com/api/v4/projects/1/packages/nuget/query",
+      "@type": "SearchQueryService/3.0.0-beta",
+      "comment": "Filter and search for packages by keyword."
+    },
+    {
+      "@id": "https://gitlab.example.com/api/v4/projects/1/packages/nuget/query",
+      "@type": "SearchQueryService/3.0.0-rc",
+      "comment": "Filter and search for packages by keyword."
+    },
+    {
+      "@id": "https://gitlab.example.com/api/v4/projects/1/packages/nuget/metadata",
+      "@type": "RegistrationsBaseUrl",
+      "comment": "Get package metadata."
+    },
+    {
+      "@id": "https://gitlab.example.com/api/v4/projects/1/packages/nuget/metadata",
+      "@type": "RegistrationsBaseUrl/3.0.0-beta",
+      "comment": "Get package metadata."
+    },
+    {
+      "@id": "https://gitlab.example.com/api/v4/projects/1/packages/nuget/metadata",
+      "@type": "RegistrationsBaseUrl/3.0.0-rc",
+      "comment": "Get package metadata."
+    },
+    {
+      "@id": "https://gitlab.example.com/api/v4/projects/1/packages/nuget/download",
+      "@type": "PackageBaseAddress/3.0.0",
+      "comment": "Get package content (.nupkg)."
+    },
+    {
+      "@id": "https://gitlab.example.com/api/v4/projects/1/packages/nuget",
+      "@type": "PackagePublish/2.0.0",
+      "comment": "Push and delete (or unlist) packages."
+    }
+  ]
+}
+```
+
+The URLs in the response have the same route prefix used to request them. If you request them with
+the group-level route, the returned URLs contain `/groups/:id/-`.
+
+## Metadata Service
+
+> Introduced in GitLab 12.8.
+
+Returns metadata for a package:
+
+```plaintext
+GET <route-prefix>/metadata/:package_name/index
+```
+
+| Attribute      | Type   | Required | Description |
+| -------------- | ------ | -------- | ----------- |
+| `package_name` | string | yes      | The name of the package. |
+
+```shell
+curl --user <username>:<personal_access_token> "https://gitlab.example.com/api/v4/projects/1/packages/nuget/metadata/MyNuGetPkg/index"
+```
+
+Example response:
+
+```json
+{
+  "count": 1,
+  "items": [
+    {
+      "@id": "https://gitlab.example.com/api/v4/projects/1/packages/nuget/metadata/MyNuGetPkg/1.3.0.17.json",
+      "lower": "1.3.0.17",
+      "upper": "1.3.0.17",
+      "count": 1,
+      "items": [
+        {
+          "@id": "https://gitlab.example.com/api/v4/projects/1/packages/nuget/metadata/MyNuGetPkg/1.3.0.17.json",
+          "packageContent": "https://gitlab.example.com/api/v4/projects/1/packages/nuget/download/MyNuGetPkg/1.3.0.17/helloworld.1.3.0.17.nupkg",
+          "catalogEntry": {
+            "@id": "https://gitlab.example.com/api/v4/projects/1/packages/nuget/metadata/MyNuGetPkg/1.3.0.17.json",
+            "authors": "",
+            "dependencyGroups": [],
+            "id": "MyNuGetPkg",
+            "version": "1.3.0.17",
+            "tags": "",
+            "packageContent": "https://gitlab.example.com/api/v4/projects/1/packages/nuget/download/MyNuGetPkg/1.3.0.17/helloworld.1.3.0.17.nupkg",
+            "summary": ""
+          }
+        }
+      ]
+    }
+  ]
+}
+```
+
+## Version Metadata Service
+
+> Introduced in GitLab 12.8.
+
+Returns metadata for a specific package version:
+
+```plaintext
+GET <route-prefix>/metadata/:package_name/index
+```
+
+| Attribute      | Type   | Required | Description |
+| -------------- | ------ | -------- | ----------- |
+| `package_name` | string | yes      | The name of the package. |
+
+```shell
+curl --user <username>:<personal_access_token> "https://gitlab.example.com/api/v4/projects/1/packages/nuget/metadata/MyNuGetPkg/1.3.0.17"
+```
+
+Example response:
+
+```json
+{
+  "@id": "https://gitlab.example.com/api/v4/projects/1/packages/nuget/metadata/MyNuGetPkg/1.3.0.17.json",
+  "packageContent": "https://gitlab.example.com/api/v4/projects/1/packages/nuget/download/MyNuGetPkg/1.3.0.17/helloworld.1.3.0.17.nupkg",
+  "catalogEntry": {
+    "@id": "https://gitlab.example.com/api/v4/projects/1/packages/nuget/metadata/MyNuGetPkg/1.3.0.17.json",
+    "authors": "",
+    "dependencyGroups": [],
+    "id": "MyNuGetPkg",
+    "version": "1.3.0.17",
+    "tags": "",
+    "packageContent": "https://gitlab.example.com/api/v4/projects/1/packages/nuget/download/MyNuGetPkg/1.3.0.17/helloworld.1.3.0.17.nupkg",
+    "summary": ""
+  }
+}
+```
+
+## Search Service
+
+> Introduced in GitLab 12.8.
+
+Given a query, search for NuGet packages in the repository:
+
+```plaintext
+GET <route-prefix>/query
+```
+
+| Attribute    | Type    | Required | Description |
+| ------------ | ------- | -------- | ----------- |
+| `q`          | string  | yes      | The search query. |
+| `skip`       | integer | no       | The number of results to skip. |
+| `take`       | integer | no       | The number of results to return. |
+| `prerelease` | boolean | no       | Include prerelease versions. Defaults to `true` if no value is supplied. |
+
+```shell
+curl --user <username>:<personal_access_token> "https://gitlab.example.com/api/v4/projects/1/packages/nuget/query?q=MyNuGet"
+```
+
+Example response:
+
+```json
+{
+  "totalHits": 1,
+  "data": [
+    {
+      "@type": "Package",
+      "authors": "",
+      "id": "MyNuGetPkg",
+      "title": "MyNuGetPkg",
+      "summary": "",
+      "totalDownloads": 0,
+      "verified": true,
+      "version": "1.3.0.17",
+      "versions": [
+        {
+          "@id": "https://gitlab.example.com/api/v4/projects/1/packages/nuget/metadata/MyNuGetPkg/1.3.0.17.json",
+          "version": "1.3.0.17",
+          "downloads": 0
+        }
+      ],
+      "tags": ""
+    }
+  ]
+}
+```