| title | description | author | ms.author | ms.date | ms.topic | ms.reviewer |
|---|---|---|---|---|---|---|
Package Content, NuGet API |
The package base address is a simple interface for fetching the package itself. |
joelverhagen |
jver |
10/26/2017 |
reference |
kraigb |
It is possible to generate a URL to fetch an arbitrary package's content (the .nupkg file) using the V3 API. The
resource used for fetching package content is the PackageBaseAddress resource found in the
service index. This resource also enables discovery of all versions of a package, listed or
unlisted.
This resource is commonly referred to as either the "package base address" or as the "flat container".
The following @type value is used:
| @type value | Notes |
|---|---|
| PackageBaseAddress/3.0.0 | The initial release |
The base URL for the following APIs is the value of the @id property associated with the aforementioned
resource @type value. In the following document, the placeholder base URL {@id} will be used. The base URL may change based on implementation or infrastructure changes within the package source so it must be dynamically fetched from the service index by the client software.
All URLs found in the package content resource support the HTTP methods GET and HEAD.
If the client knows a package ID and wants to discover which package versions the package source has available, the client can construct a predictable URL to enumerate all package versions. This list is meant to be a "directory listing" for the package content API mentioned below.
Note
This list contains both listed and unlisted package versions.
GET {@id}/{LOWER_ID}/index.json
| Name | In | Type | Required | Notes |
|---|---|---|---|---|
| LOWER_ID | URL | string | yes | The package ID, lowercased |
The LOWER_ID value is the desired package ID lowercased using the rules implemented by .NET's
System.String.ToLowerInvariant() method.
If the package source has no versions of the provided package ID, a 404 status code is returned.
If the package source has one or more versions, a 200 status code is returned. The response body is a JSON object with the following property:
| Name | Type | Required | Notes |
|---|---|---|---|
| versions | array of strings | yes | The versions available |
The strings in the versions array are all lowercased,
normalized NuGet version strings. The version
strings do not contain any SemVer 2.0.0 build metadata.
The intent is that the version strings found in this array can be used verbatim for the LOWER_VERSION tokens found
in the following endpoints.
GET https://api.nuget.org/v3-flatcontainer/owin/index.json
Make sure to fetch the base URL (https://api.nuget.org/v3-flatcontainer/ in this sample) from the service index as mentioned in the base URL section.
[!code-JSON package-base-address-index.json]
If the client knows a package ID and version and wants to download the package content, they only need to construct the following URL:
GET {@id}/{LOWER_ID}/{LOWER_VERSION}/{LOWER_ID}.{LOWER_VERSION}.nupkg
| Name | In | Type | Required | Notes |
|---|---|---|---|---|
| LOWER_ID | URL | string | yes | The package ID, lowercase |
| LOWER_VERSION | URL | string | yes | The package version, normalized and lowercased |
Both LOWER_ID and LOWER_VERSION are lowercased using the rules implemented by .NET's
System.String.ToLowerInvariant()
method.
The LOWER_VERSION is the desired package version normalized using NuGet's version
normalization rules. This means that build metadata
that is allowed by the SemVer 2.0.0 specification must be excluded in this case.
If the package exists on the package source, a 200 status code is returned. The response body will be the package content itself.
If the package does not exist on the package source, a 404 status code is returned.
GET https://api.nuget.org/v3-flatcontainer/newtonsoft.json/9.0.1/newtonsoft.json.9.0.1.nupkg
Make sure to fetch the base URL (https://api.nuget.org/v3-flatcontainer/ in this sample) from the service index as mentioned in the base URL section.
The binary stream that is the .nupkg for Newtonsoft.Json 9.0.1.
If the client knows a package ID and version and wants to download the package manifest, they only need to construct the following URL:
GET {@id}/{LOWER_ID}/{LOWER_VERSION}/{LOWER_ID}.nuspec
| Name | In | Type | Required | Notes |
|---|---|---|---|---|
| LOWER_ID | URL | string | yes | The package ID, lowercase |
| LOWER_VERSION | URL | string | yes | The package version, normalized and lowercased |
Both LOWER_ID and LOWER_VERSION are lowercased using the rules implemented by .NET's
System.String.ToLowerInvariant() method.
The LOWER_VERSION is the desired package version normalized using NuGet's version
normalization rules. This means that build metadata
that is allowed by the SemVer 2.0.0 specification must be excluded in this case.
If the package exists on the package source, a 200 status code is returned. The response body will be the package manifest, which is the .nuspec contained in the corresponding .nupkg. The .nuspec is an XML document.
If the package does not exist on the package source, a 404 status code is returned.
GET https://api.nuget.org/v3-flatcontainer/newtonsoft.json/6.0.4/newtonsoft.json.nuspec
Make sure to fetch the base URL (https://api.nuget.org/v3-flatcontainer/ in this sample) from the service index as mentioned in the base URL section.
[!code-XML newtonsoft.json.6.0.4.xml]