Commit dc611b97 authored by Nick Gaskill's avatar Nick Gaskill

Merge branch '219419-nuget-api-docs' into 'master'

Add NuGet API docs

See merge request gitlab-org/gitlab!57614
parents 4c4ba45a 16e864d9
---
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": ""
}
]
}
```
......@@ -18,6 +18,9 @@ The Package Registry works with:
- [.NET Core CLI](https://docs.microsoft.com/en-us/dotnet/core/tools/)
- [Visual Studio](https://visualstudio.microsoft.com/vs/)
For documentation of the specific API endpoints that these
clients use, see the [NuGet API documentation](../../../api/packages/nuget.md).
## Install NuGet
The required minimum versions are:
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment