- 22 Jan 2024
- 9 Minutes to read
- Print
- DarkLight
- PDF
Feed Management API
- Updated on 22 Jan 2024
- 9 Minutes to read
- Print
- DarkLight
- PDF
The Feed Management API Endpoints offer a simple mechanism for querying, creating, and updating feeds, and related data:
- Create Feed - creates a specified feed
- Get Feed - describes an specified feed
- List Feeds - describes all feeds, filtered as specified
- Update Feed - updates a specified feed
- Delete Feed - deletes a specified feed
Authenticating to Feed Management 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 the Create Feed endpointOverwrite/Delete is required for the Delete Feed endpoint |
Personal API Key | Feeds_ViewFeed is required for all endpointsFeeds_AddPackage is required for the Create Feed endpointFeeds_DeletePackage is required for the Delete Feed 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 list feeds endpoint, you could specify the API key as follows:
curl -X GET --header "X-ApiKey: abc12345" "https://proget.corp.local/api/management/feeds/list"
Data Specifications
Feed Object Attributes
Feed
is a set of key/value pairs that correspond to the fields on a Feed. It's used as input for the Create Feed endpoint, and output for the Get Feed and List Feed endpoints.
name
and feedType
properties are required for the Create Feed Endpoint. Unless otherwise indicated, omitting a property or supplying null
as the value will keep the current setting.
Property | Format | Details |
---|---|---|
name | string | the unique name of the feed; must not contain characters that require URL escaping |
feedType | string | denotes the feed type; valid values are: universal , nuget , chocolatey , npm , bower , maven , powershell , docker , rubygems , vsix , asset , romp , debian , pypi , helm , rpm , conda |
description | string | a description displayed with the ProGet feed name in the UI; supplying null removes the description |
active | bool | indicates whether the feed is active (true ) or disabled (false ) |
cacheConnectors | bool | indicates whether connector caching is enabled for the feed |
dropPath | string | disk path accessible to ProGet's service where packages may be added to the feed; supplying null disables the drop path |
packagesPath | string | absolute disk path for package storage if a packageStore is not specified, supplying null will use a path relative to the value of the Storage.PackagesRootPath setting |
packageStore | string | serialized configuration for a custom package store such as Amazon S3 or Azure Blob; see Persisted XML; supplying null will use ProGet-managed storage as specified by the packagesPath |
allowUnknownLicenses | bool | indicates whether packages with unknown licenses are allowed; supplying null will inherit the value of the Feeds.AllowUnknownLicenseDownloads setting |
allowedLicenses | string[] | array of SPDX license identifiers (e.g. MIT , LGPL-3.0 ) known to ProGet (visible on the Manage Licenses page) allowed to be downloaded from the feed; supply an empty array to remove them all |
blockedLicenses | string[] | array of SPDX license identifiers (e.g., MIT , LGPL-3.0 ) known to ProGet (visible on the Manage Licenses page) blocked from being downloaded from the feed; supply an empty array to remove them all |
connectors | string[] | array of connectors for the feed; supply an empty array to remove all feed connectors |
vulnerabilitySources | string[] | array of vulnerability sources for the feed; supply an empty array to remove all vulnerability sources |
retentionRules | object[] | array of retention rule objects that define the retention rules for the feed; supply an empty array to remove all retention rules from the feed |
packageFilters | string[] | array of serialized configurations that define the custom package filters; see Persisted XML; supply an empty array to remove all package filters |
packageAccessRules | string[] | array of serialized configurations that define the custom package access rules; see Persisted XML; supply an empty array to remove all package access rules |
replication | object | a replication object that defines the replication configuration for the feed |
variables | object | an object whose property names represent variable names, and whose property values represent the variable value; supply an object with no properties to remove all variables. Naming rules:
|
packageStatisticsEnabled | bool | indicates whether individual downloads for advanced statistics should be recorded (requires ProGet 2022.26 or later) |
restrictPackageStatistics | bool | indicates whether viewing download statistics are restricted to Feed Administrators (requires ProGet 2022.26 or later) |
deploymentRecordsEnabled | bool | indicates whether packages deployment records should be recorded (requires ProGet 2022.26 or later) |
usageRecordsEnabled | bool | indicates whether usage records should be enabled (requires ProGet 2022.26 or later) |
vulnerabilitiesEnabled | bool | indicates whether vulnerability information should be displayed and download blocking rules should be enforced; not supported on all feed types (requires ProGet 2022.26 or later) |
licensesEnabled | bool | indicates whether license information should be displayed and download blocking rules should be enforced; not supported on all feed types (requires ProGet 2022.26 or later) |
useWithProjects | bool | indicates whether package usage in Projects & Releases (SCA) should be displayed (requires ProGet 2022.26 or later) |
retentionRulesEnabled | bool | indicates whether retention rules are enabled on the feed (requires ProGet 2023.25 or later) |
JSON Object
{
"name": "myNugetFeed",
"feedType": "nuget",
"description": "Example NuGet Feed",
"active": true,
"cacheConnectors": true,
"dropPath": "/path/to/drop",
"packagesPath": "/path/to/packages",
"packageStore": null,
"allowUnknownLicenses": true,
"allowedLicenses": ["MIT", "GPL-3.0"],
"blockedLicenses": [],
"connectors": ["connector1", "connector2"],
"vulnerabilitySources": ["source1", "source2"],
"retentionRules": [
{
"deletePrereleaseVersions": false,
"deleteCached": true,
"keepVersionsCount": 5,
"keepUsedWithinDays": 30,
"triggerDownloadCount": 100,
"keepPackageIds": ["package1", "package2"],
"deletePackageIds": [],
"keepVersions": ["1.0.0", "2.0.0"],
"deleteVersions": []
}
],
"packageFilters": ["filter1", "filter2"],
"packageAccessRules": ["rule1", "rule2"],
"replication":
{
"clientMode": "pushonly",
"serverMode": "readonly",
"clientToken": "client-token",
"serverToken": "server-token",
"sourceUrl": "http://proget.corp.locall"
},
"variables":
{
"variable1": "value1",
"variable2": "value2"
},
"packageStatisticsEnabled": true,
"restrictPackageStatistics": true,
"deploymentRecordsEnabled": true,
"usageRecordsEnabled": true,
"vulnerabilitiesEnabled": true,
"licensesEnabled": true,
"useWithProjects": true,
"retentionRulesEnabled": true
}
NuGet Only
Property | Format | Details |
---|---|---|
symbolServerEnabled | bool | indicates whether the NuGet symbol server is enabled; only applies to NuGet-like feed types |
stripSymbols | bool | indicates whether symbol files (i.e., .pdb files) are removed from a NuGet-like package when downloaded |
stripSource | bool | indicates whether source files (i.e., files under src/ in the package) are removed from a NuGet-like package when downloaded |
stripSignature | bool | indicates signature files should be stripped on NuGet packages when downloaded (requires ProGet 2022.27 or later) |
useApiV3 | bool | indicates whether the NuGet v3 API should be used on NuGet feeds (requires ProGet 2022.27 or later) |
JSON Object
{
"symbolServerEnabled": true,
"stripSymbols": false,
"stripSource": true,
"stripSignature": false,
"useApiV3": true
}
RetentionRule Object Attributes
RetentionRule
is a subset of attributes on the Feed Object.
Property | Format | Details |
---|---|---|
deletePrereleaseVersions | bool | when true , the retention rule only applies to pre-release packages (e.g., they have a pre-release part in their semantic version, or are SNAPSHOT versions) |
deleteCached | bool | when true , the retention rule only applies to cached connector packages |
keepVersionsCount | int | when set to n , the retention rule always keeps the latest n versions of a matching package; this value is ignored for Docker feeds |
keepUsedWithinDays | int | when set to n , the retention rule always keeps package versions if they have been downloaded within the past n days |
triggerDownloadCount | int | when set to n , the retention rule always keeps versions that have been downloaded more than n times |
keepPackageIds | string[] | array of package names/identifiers that are kept regardless of other filters; supports wildcards but not negations, as any matching package is always kept |
deletePackageIds | string[] | array of package names/identifiers that are deleted if they match all other filters; supports wildcards but not negations (use keepPackageIds for exclusions) |
keepVersions | string[] | array of package versions that are kept regardless of other filters; supports wildcards but not negations, as any matching package version is always kept |
deleteVersions | string[] | array of package versions that are deleted if they match all other filters; supports wildcards but not negations (use keepVersions for exclusions) |
sizeTriggerKb | int | when set to n , indicates the minimum number of kilobytes of storage that must be used in order to run retention; used storage is calculated per-package or per-feed based on the value of sizeExclusive |
sizeExclusive | bool | when true and sizeTriggerKb is set to non-null n , retention is run only on packages whose disk size is greater than n kilobytes; when false and sizeTriggerKb is set to non-null n , retention is run when the entire feed size is greater than n kilobytes; this value is ignored when sizeTriggerKb is null |
JSON Object
{
"deletePrereleaseVersions": false,
"deleteCached": true,
"keepVersionsCount": 5,
"keepUsedWithinDays": 30,
"triggerDownloadCount": 100,
"keepPackageIds": ["package1", "package2"],
"deletePackageIds": [],
"keepVersions": ["1.0.0", "2.0.0"],
"deleteVersions": [],
"sizeTriggerKb": 1024,
"sizeExclusive": true
}
Replication Object Attributes
Replication
is a subset of attributes on the Feed Object.
Note that replication in ProGet 2022 is no longer configured at the feed level; as such, this model is not available on the feed API.
Property | Format | Details |
---|---|---|
clientMode | string | the client replication mode configuration, one of disabled , pullonly , pushonly , mirror ; more info |
serverMode | string | the server replication mode configuration, one of disabled , readonly , writeonly , readwrite ; more info |
clientToken | string | the token used to authenticate with a replication server; this field is not returned by list or get endpoints; this field is required when clientMode is set to anything other than disabled |
serverToken | string | the token that must be specified by a replication client to connect; this field is not returned by list or get endpoints; this field is required when serverMode is set to anything other than disabled |
sourceUrl | string | the URL of the replication server; this field is required when clientMode is set to anything other than disabled |
JSON Object
{
"clientMode": "pushonly",
"serverMode": "readonly",
"clientToken": "client-token",
"serverToken": "server-token",
"sourceUrl": "http://replication-server-url"
}
Notes about Data
Wildcards and Negations
Certain fields noted above support wildcard and negation syntax. For example, the value ["Microsoft.*", "Castle.*", "!Rubbishsoft.*"]
has the following properties:
- includes any packages that start with
Microsoft.
orCastle.*
- excludes any packages that start with
Rubbishsoft.
Feed & Package Types
In ProGet UI, Chocolatey and PowerShell are represented as separate feed types, even though they only contain NuGet packages and use the same NuGet API. For this reason, in ProGet UI, you can switch the type of a feed' between NuGet, Chocolatey, and PowerShell at any time, but not between other feed types.
The API allows feed types to be changed only within the following feed type groups (anything else generates a 400
error):
universal
andromp
nuget
,chocolatey
, andpowershell
Persisted XML Configuration
Because package stores, package filters, and package access rules are implemented by extensible runtime components (i.e., you can create your own using the Inedo SDK), ProGet stores configuration for these components in "Persisted XML", which is a lightweight object serialization format that Inedo products use.
The easiest way to see what an object's persisted XML will look like is to create it in the UI, then look at the XML in either the database or the API List Feeds or Get Feed request. As a reference, we've provided the persisted XML for both supported package stores and a general example:
AWS
<Inedo.ProGet.Extensions.AWS.PackageStores.S3FileSystem Assembly="AWS">
<Properties AccessKey="{publicAccessKey}" SecretAccessKey="{privateAccessKey}" BucketName="{bucketName}" TargetPath="{pathInsideBucketDefaultIsRoot}" ReducedRedundancy="{False}" MakePublic="{False}" Encrypted="False" RegionEndpoint="{us-east-1}" CustomServiceUrl="{customServiceUrl}" />
</Inedo.ProGet.Extensions.AWS.PackageStores.S3FileSystem>
Azure Blob Storage
<Inedo.ProGet.Extensions.Azure.PackageStores.AzureFileSystem Assembly="Azure">
<Properties ConnectionString="{DefaultEndpointsProtocol=https;AccountName=account-name;AccountKey=account-key}" ContainerName="{blobContainerName}" TargetPath="{pathToFilesDefaultIsRoot}" />
</Inedo.ProGet.Extensions.Azure.PackageStores.AzureFileSystem>
Custom Extension Format
<{FullNamespace.ClassName} Assembly="AssemblyName">
<Properties PropertyNameA="{property value}" PropertyNameB="1000" />
</{FullNamespace.ClassName}>
Default Feed Disk Path
If you don't specify a disk path for a feed to use, ProGet uses a path 'based on the 'system-generated ID. This means that, just as in UI, if you delete a feed and then recreate it with the same name, the disk path will be different.