- 08 Apr 2024
- 5 Minutes to read
- Print
- DarkLight
- PDF
Common Packages API
- Updated on 08 Apr 2024
- 5 Minutes to read
- Print
- DarkLight
- PDF
The Common Package API has endpoints to query, download, publish, delete, and perform other operations on packages in package-based feeds, regardless of the package type:
- Query Latest Packages - describes the latest version of a specified package
- Query Package Versions - describes all versions of a package, filtered as specified
- Download Package - downloads a specified Package file
- Upload Package - uploads a package file to a feed
- Delete Package - deletes a package from a feed
- Set Package Status - sets the listed or deprecated status of a specified package
The Common Package API is available starting from ProGet 2023.
This API works with packages stored in ProGet (i.e. local or cached packages). To query remote packages from connectors, you'll need to use the API specific to the feed type.
Also note that Maven, Docker, and Bower don't have "packages" like other feed types, and will not work with this API.
Authenticating to Common Package API Endpoints
The following is a summary of access types and their corresponding requirements for various API keys types and endpoints within this API.
Access Type | Requirements |
---|---|
System API Keys | Use/Manage Feeds |
Feed API Keys | View/Download is required for all endpointsAdd/Repackage is required for Upload Packages endpointOverwrite/Delete is required for Delete Packages endpoint |
Personal API Key | Feeds_ViewFeed is required for all endpointsFeeds_AddPackage is required for Upload Package endpointFeeds_DeletePackage is required for Delete Packages endpoint |
No API Key | anonymous or authenticated user must have at least Feeds_ViewFeed |
To specify an API Key, use the request header (X-ApiKey
), querystring (key
), or api:«api-key»
as the username. See API Key Usage to learn more.
For example, to authenticate with the API key abc12345
to the query packages endpoint, you could specify the API key as follows:
curl -X GET --header "X-ApiKey: abc12345" "https://proget.corp.local/api/packages/MyNugetFeed/versions"
If the provided API key is either missing, unknown/incorrect or does not have permission, the following message is returned:
403 The specified API key does not have the proper permissions to perform this action.
Package Identifiers (Group/Name/Version vs Purl)
Endpoints that work with a single package version (e.g. downloading, deleting, etc.) require identifying a single version package using querystring parameters. This can be done by specifying multiple parameters (name
and version
, and sometimes group
and qualifier
) or a single paramter (purl
).
Using Multiple Parameters to Identify a Package
Identifying a package version requires up to four different components, depending on the type of package.
Argument | Details | Endpoints Used |
---|---|---|
name | the name/id of package to download | all |
version | the version of package to download | all |
group | used only by Universal and npm feeds; for npm, this is the "scope" with the the @ replaced by %40 | query package version , query latest package , download package , delete package , set package status |
qualifier | used by some feeds (like Debian and rubygems) for attributes like architecture | query package version , query latest package , download package , delete package , set package status |
To download version 12.3.1
of the @angular/animation
package, you would need to construct a url as follows:
/api/packages/NpmFeed/download?group=angular&name=animation&version=12.3.1
To download version 3.9.2-3
of the python3
package with the amd64 architecture, you would need to construct a url as follows:
/api/packages/MyDebianFeed/download?group=main&name=python3&version=3.9.2-3&qualifier=arch%3Damd64
Using a Purl to Identify a Package
To simplify package identification, you can also specify a purl
(i.e. Package Url) that is compatible across all package types.
To download version 12.3.1 of the @angular/animation
package, you would need to construct a purl
as follows:
/api/packages/NpmFeed/download?purl=pkg:npm/%40angular/animation@12.3.1
This follows the purl-spec, and you can also find it on the PackageVersion Object
Documentation Conventions
In the endpoints that require package version identifier, we will use «package-identifiers»
to reference the one or multiple parameters that you can use.
Data Specifications
PackageVersion Object Attributes
PackageVersion
is a set of key/value pairs that correspond to the fields on a Package. It's used as output data for the Query Latest Packages Endpoint and Query Package Version as a JSON-formatted object.
Note that some values are optional (indicated by string?
), and may be set to null
or omitted.
Property | Format | Notes |
---|---|---|
purl | string | Package purl |
group | string? | Only included if package has a group |
name | string | Package name/id |
version | float | Latest version of package |
qualifier | string? | Qualifier portion of PUrl if relevant |
totalDownloads | number | Number of downloads of all versions of the package |
downloads | int | Number of downloads of the latest version of the package |
published | datetime | Timestamp when package was published to the feed |
publishedBy | string? | Name of user that published the package |
size | int | Size of package file in bytes |
listed | bool? | Indicates whether package is visible to searches (default true ) |
allow | bool? | Download override flag for package (default null ) |
md5 | string | md5 hash of package |
sha1 | string | sha1 hash of package |
sha256 | string | sha256 hash of package |
sha512 | string | sha512 hash of package |
deprecation | object? | A DeprecationInfo Object |
JSON Object:
{
"purl":"pkg:nuget/myNugetPackage@1.0.0",
"group":null,
"name":"MyNugetPackage",
"version":"1.2.3",
"totalDownloads":321,
"downloads":23,
"published":"2023-10-17T02:43:00.717Z",
"publishedBy":"Admin",
"size":2441966,
"md5":"94d7f4cce0663c6a30340fe6fec831da",
"sha1":"f418efd4238eb069cf38d1c86f4edc34444777dd",
"sha256":"872fc189e638ab1056555b03aaa38f68bcb54286e221aa646eb1129babf63c77",
"sha512":"99b252bc77d1c5f5f7b51fd4ea7d5653e9961d7b3061cf9207f8643a9c
7cc9965eebc84d6467f2989bb4723b1a244915cc232a78f894e8b748ca882a7c89fb92"
"deprecation":
{
"reason": ['Legacy'],
"message": "Legacy version, deprecated on 01/01/2024",
"alternateName": null,
"alternateVersions": null
}
}
PackageStatus Object Attributes
PackageStatus
is a subset of attributes on the PackageVersion Object that correspond to settable fields. It's used as input for various endpoints:
All of the values are optional and may be omitted. An omitted property will not be set.
Property | Format | Notes |
---|---|---|
listed | bool | Indicates whether package is visible to searches (default true ) |
allow | bool? | Download override flag for package (default null ) |
deprecation | object? | A DeprecationInfo Object or null when not deprecated |
JSON Object:
{
"listed": true,
"allow": null,
"deprecation":
{
"reason": ['Legacy'],
"message": "Legacy version, deprecated on 01/01/2024",
"alternateName": null,
"alternateVersions": null
}
}
DeprecationInfo Object Attributes
DeprecationInfo
is a set of key/value pairs that is used on the PackageVersion and PackageStatus Objects.
Note that all values are optional (indicated by string?
), and may be set to null
or omitted.
Property | Format | Notes |
---|---|---|
reason | array? | Array of reasons for depreciation. Valid deprecation reasons are ONLY Legacy , CriticalBugs , andOther . Non-valid reasons will default to Legacy . |
message | string? | Message describing the reasons for depreciation, used with "Other " reason . |
alternateName | string? | Alternate name for the package |
alternateVersions | string? | Alternate versions of the package |
JSON Object:
{
"reason": ['Legacy'],
"message": "Legacy version, deprecated on 01/01/2024",
"alternateName": null,
"alternateVersions": null
}