- 24 Mar 2023
- 15 Minutes to read
-
Print
-
DarkLight
-
PDF
Feed Management API
- Updated on 24 Mar 2023
- 15 Minutes to read
-
Print
-
DarkLight
-
PDF
The Feed Management API Endpoints offer a simple mechanism for querying, creating, and updating feeds, connectors, vulnerability sources, licenses & rules, and related data. The primary use cases for these endpoints are:
- provision and configure feeds with infrastructure automation tools such as Otter
- allow external tools to query/monitor feed information and metadata
- duplicate feed configuration with minimal effort
- copy feed configuration across multiple ProGet instances
- assist in receiving support by submitting configuration to engineers or the community
This API is available starting in ProGet 5.2.
Authentication
For security and simplicity, these endpoints require that a Feed Management API Key be created first. This key can be submitted to the API using any of the methods documented in the API Key Usage section.
Object Models
Each endpoint sends and receives entities as JSON objects. The specific objects are defined as follows:
Bold* indicates a property is required for the create endpoint. Unless otherwise indicated, omitting a property or supplying null
as the value will keep the current setting.
Feed Data Model
Property | 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 |
description |
string - a description displayed with the ProGet feed name in the UI; supplying null removes the description |
active |
boolean - indicates whether the feed is active (true ) or disabled (false ) |
cacheConnectors |
boolean - 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 |
boolean - 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 |
symbolServerEnabled |
boolean - indicates whether the NuGet symbol server is enabled; only applies to NuGet-like feed types |
stripSymbols |
boolean - indicates whether symbol files (i.e., .pdb files) are removed from a NuGet-like package when downloaded |
stripSource |
boolean - indicates whether source files (i.e., files under src/ in the package) are removed from a NuGet-like package when downloaded |
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 |
RetentionObject[] - 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 |
ReplicationObject - 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 |
boolean - indicates whether individual downloads for advanced statistics should be recorded (requires ProGet 2022.26 or later) |
restrictPackageStatistics |
boolean - indicates whether viewing download statistics are restricted to Feed Administrators (requires ProGet 2022.26 or later) |
deploymentRecordsEnabled |
boolean - indicates whether packages deployment records should be recorded (requires ProGet 2022.26 or later) |
usageRecordsEnabled |
boolean - indicates whether usage records should be enabled (requires ProGet 2022.26 or later) |
vulnerabilitiesEnabled |
boolean - 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 |
boolean - 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 |
boolean - indicates whether package usage in Projects & Releases (SCA) should be displayed (requires ProGet 2022.26 or later) |
Connector Data Model
Property | Details |
---|---|
name * |
string - the unique name of the connector; must not include characters that require URL escaping; max 100 characters |
feedType * |
string - denotes the feed type; valid values are: universal , nuget , chocolatey , npm , maven , powershell , docker , rubygems , vsix , asset , romp , pypi , helm |
url |
string - the URL of the connector |
username |
string - the username used for authentication at the connector URL |
password |
string - the password used for authentication at the connector URL |
timeout |
integer - the timeout (in seconds) used when making a request to the connector URL |
filters |
string[] - array of connector filters; supply an empty array to remove all filters; supports wildcards and negations |
metadataCacheEnabled |
boolean - indicates whether metadata caching is enabled on the connector |
metadataCacheMinutes |
integer - the number of minutes a connector metadata request to a specific URL is cached by ProGet (default: 30 ) |
metadataCacheCount |
integer - the number of URL-specific metadata requests cached by ProGet (default: 100 ) |
Retention Rule Data Model
Note that this is only used within a feed entity's retentionRules
property.
Property | Details |
---|---|
deletePrereleaseVersions |
boolean - 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 |
boolean - when true , the retention rule only applies to cached connector packages |
keepVersionsCount |
integer - 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 |
integer - when set to n , the retention rule always keeps package versions if they have been downloaded within the past n days |
triggerDownloadCount |
integer - 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 |
integer - 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 |
boolean - 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 |
Replication Data Model
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.
Note that this is only used within a feed entity's replication
property.
Property | 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 in order 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 |
License Data Model
Property | Details |
---|---|
licenseId * |
string - an SPDX license identifier |
title |
string - a friendly name for the license |
urls |
string[] - array of URLs used to map a package license to SPDX identifer |
allowed |
boolean - indicates whether a license is allowed (true ) or blocked (false ) at the global level |
allowedFeeds |
string[] - array of feed names that contain a license rule set to allow the license |
blockedFeeds |
string[] - array of feed names that contain a license rule set to block the license |
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 or get 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}>
Names & IDs
Since one of the main use cases of the Feed Management API is to maintain feed configuration across multiple instances of ProGet, using or disclosing the read-only system-generated identifiers for entities is not practical. For this reason, these IDs are not used by the API.
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.
Endpoint Specifications
All of the management endpoints follow the same convention:
GET/POST /api/management/«entity-type»/«action-type»/[«entity-name»]
entity-type
is one offeeds
,connectors
, orlicenses
action-type
is one of list, get, create, update, or deleteentity-name
is the name identifier of the entity being updated, or deleted; it is not valid on alist
orcreate
action type- all endpoints require an API key with Feed Management permissions (and additionally Manage Licenses permissions for
/licenses
endpoints). This key can be supplied to the endpoint via any of the documented API Key Usage methods indent
may suppllied in the query string for get or list endpoints to improve readabilityapplication/json
content type is required for any data sent viaPOST
/PUT
/PATCH
List Entities Endpoint
Returns an array of objects representing the specified entity-type
(feeds, connectors, or licenses).
URL Format:
GET/HEAD /api/management/«entity-type»/list
Response Codes:
Code | Description |
---|---|
200 |
Success |
403 |
Invalid/unauthorized API key, or impersonated user not granted Feeds_Manage privilege |
Example Responses:
GET/HEAD /api/management/feeds/list
[
{
"name": "Default",
"feedType": "nuget",
"active": true,
"cacheConnectors": true,
"allowUnknownLicenses": true,
"allowedLicenses": ["MIT", "BSD-2-Clause", "BSD-3-Clause", "Apache-2.0"],
"blockedLicenses": ["RSGPL"],
"symbolServerEnabled": true,
"stripSymbols": true,
"stripSource": true,
"connectors": [
"nuget.org"
],
"vulnerabilitySources": [],
"retentionRules": [
{
"deletePrereleaseVersions": false,
"keepVersionsCount": 10,
"keepUsedWithinDays": 90,
"deletePackageIds": [
"InedoLib",
"InedoIcons",
"Inedo.LicenseCreator"
],
"keepPackageIds": null,
"keepVersions": null,
"deleteVersions": null,
"deleteCached": false,
"sizeTriggerKb": null,
"sizeExclusive": true,
"triggerDownloadCount": 1
}
],
"packageFilters": {},
"packageAccessRules": {},
"replication": {},
"variables": {}
},
{ ... }
]
GET/HEAD /api/management/connectors/list
[
{
"name": "nuget.org",
"url": "https://www.nuget.org/api/v2/",
"feedType": "NuGet",
"timeout": 10,
"metadataCacheEnabled": true,
"metadataCacheMinutes": 1440,
"metadataCacheCount": 100,
"filters": []
},
{
"name": "chocolatey.org",
"url": "http://chocolatey.org/api/v2/",
"feedType": "NuGet",
"timeout": 10,
"metadataCacheEnabled": true,
"metadataCacheMinutes": 30,
"metadataCacheCount": 100,
"filters": []
},
{
"name": "Inedo",
"url": "https://proget.inedo.com/feeds/Extensions",
"feedType": "ProGet",
"timeout": 10,
"metadataCacheEnabled": true,
"metadataCacheMinutes": 30,
"metadataCacheCount": 100,
"filters": []
}
]
GET/HEAD /api/management/licenses/list
[
{
"licenseId": "0BSD",
"title": "BSD Zero Clause License",
"urls": [
"landley.net/toybox/license.html",
"spdx.org/licenses/0BSD.html"
],
"allowed": true,
"allowedFeeds": ["OpenLicenses"],
"blockedFeeds": []
},
{
"licenseId": "AAL",
"title": "Attribution Assurance License",
"urls": [
"spdx.org/licenses/AAL.html",
"www.opensource.org/licenses/attribution"
],
"allowed": true,
"allowedFeeds": [],
"blockedFeeds": []
},
{ ... }
]
Get Entity Endpoint
Returns a single data object with the name entity-name
for the specified entity-type
.
URL Format:
GET/POST /api/management/«entity-type»/get/«entity-name»
Response Codes:
Code | Description |
---|---|
200 |
Success |
403 |
Invalid/unauthorized API key, or impersonated user not granted Feeds_Manage privilege |
404 |
Entity not found |
Example Responses:
GET/HEAD /api/management/feeds/get/Default
{
"name": "Default",
"feedType": "nuget",
"active": true,
"cacheConnectors": true,
"allowUnknownLicenses": true,
"allowedLicenses": ["MIT", "BSD-2-Clause", "BSD-3-Clause", "Apache-2.0"],
"blockedLicenses": ["RSGPL"],
"symbolServerEnabled": true,
"stripSymbols": true,
"stripSource": true,
"connectors": [
"nuget.org"
],
"vulnerabilitySources": [],
"retentionRules": [
{
"deletePrereleaseVersions": false,
"keepVersionsCount": 10,
"keepUsedWithinDays": 90,
"deletePackageIds": [
"InedoLib",
"InedoIcons",
"Inedo.LicenseCreator"
],
"keepPackageIds": null,
"keepVersions": null,
"deleteVersions": null,
"deleteCached": false,
"sizeTriggerKb": null,
"sizeExclusive": true,
"triggerDownloadCount": 1
}
],
"packageFilters": {},
"packageAccessRules": {},
"replication": {},
"variables": {}
}
GET/HEAD /api/management/connectors/get/Inedo%20Den
{
"name": "Inedo",
"url": "https://proget.inedo.com/feeds/Extensions",
"feedType": "ProGet",
"timeout": 10,
"metadataCacheEnabled": true,
"metadataCacheMinutes": 30,
"metadataCacheCount": 100,
"filters": []
}
GET/HEAD /api/management/licenses/get/0BSD
{
"licenseId": "0BSD",
"title": "BSD Zero Clause License",
"urls": [
"landley.net/toybox/license.html",
"spdx.org/licenses/0BSD.html"
],
"allowed": true,
"allowedFeeds": ["OpenLicenses"],
"blockedFeeds": []
}
Create Entity Endpoint
Creates a specified entity-type
with the properties defined in the body of the request. Refer to the Object Models for the JSON format of the entities, and the caveats related to specific properties (i.e., supplying null
values vs. empty arrays, required field combinations, etc.)
URL Format:
POST/PUT /api/management/«entity-type»/create
Response Codes:
Code | Description |
---|---|
201 |
Success (created); response body contains new object |
400 |
Validation error; the response body content will contain specific error messages (e.g., "feed name is required", "invalid feed type") |
403 |
Invalid/unauthorized API key, or impersonated user not granted Feeds_Manage privilege |
422 |
Invalid entity; occurs when a property of the entity references a missing entity; the response body content will contain specific error messages e.g. "connector 'NonExistent' does not exist" |
Examples:
POST/PUT /api/management/feeds/create
Header | Value |
---|---|
X-ApiKey |
secure123 |
Content-Type |
application/json |
Body:
{
"name": "InedoExtensions",
"feedType": "universal",
"active": true
}
PowerShell Example:
Invoke-RestMethod -Method POST `
-Uri http://{proget-server}/api/management/feeds/create `
-ContentType "application/json" `
-Headers @{"X-ApiKey" = "secure123"} `
-Body (@{name="InedoExtensions";feedType="universal";active=$true} | ConvertTo-Json)
Update Entity Endpoint
Updates a specified entity-type
with an existing name entity-name
using the properties defined in the request body. This endpoint supports partial updating by only updating the properties that are supplied in the request. Refer to the Object Models for the JSON format of the entities, and the caveats related to specific properties (i.e., supplying null
values vs. empty arrays, required field combinations, etc.)
For most properties, omitting scalar values will keep the existing or default values. When updating a feed property with an array value, the array value supplied should be considered the "desired state" (regardless of POST
or PATCH
). For example, if a feed has connectors A and B, supplying connectors: ["C"]
in the feed object will remove connectors A and B from the feed. To append values, perform a get first, then append the existing values returned in the update request.
URL Format:
POST/PATCH /api/management/«entity-type»/update/«entity-name»
Response Codes:
Code | Description |
---|---|
201 |
Success (updated); response body contains updated object |
400 |
Validation error; the response body content will contain specific error messages (e.g., "feed name is required", "invalid feed type") |
403 |
Invalid/unauthorized API key, or impersonated user not granted Feeds_Manage privilege |
404 |
Entity entity-name does not exist |
422 |
Invalid entity; occurs when a property of the entity references a missing entity; the response body content will contain specific error messages (e.g., "connector 'NonExistent' does not exist") |
Examples:
POST/PATCH /api/management/feeds/update/InedoExtensions
Header | Value |
---|---|
X-ApiKey |
secure123 |
Content-Type |
application/json |
Body:
{
"description": "This feed serves as a proxy for Inedo SDK extensions."
}
PowerShell Example:
Invoke-RestMethod -Method POST `
-Uri http://{proget-server}/api/management/feeds/update/InedoExtensions `
-ContentType "application/json" `
-Headers @{"X-ApiKey" = "secure123"} `
-Body (@{description="This feed serves as a proxy for Inedo SDK extensions."} | ConvertTo-Json)
POST/PATCH /api/management/connectors/update/nuget.org
Header | Value |
---|---|
X-ApiKey |
secure123 |
Content-Type |
application/json |
Body:
{
"url": "https://nuget/org/api/v2"
}
PowerShell Example:
Invoke-RestMethod -Method POST `
-Uri http://{proget-server}/api/management/connectors/update/nuget.org`
-ContentType "application/json" `
-Headers @{"X-ApiKey" = "secure123"} `
-Body (@{url="https://nuget/org/api/v2"} | ConvertTo-Json)
POST/PATCH /api/management/feeds/update/InedoExtensions
Header | Value |
---|---|
X-ApiKey |
secure123 |
Content-Type |
application/json |
Body:
{
"retentionRules": [
{
"keepUsedWithinDays": 30,
"deleteCached": true
},
{
"keepVersionsCount": 10,
"keepUsedWithinDays": 90,
"deletePackageIds": [
"InedoLib",
"InedoIcons",
"Inedo.LicenseCreator"
],
"sizeExclusive": true,
"triggerDownloadCount": 1
},
{
"deletePrereleaseVersions": true,
"keepVersionsCount": 5,
"keepUsedWithinDays": 30
}
]
}
This example configures the "InedoExtensions" feed with the following retention rules:
- delete cached connector packages that haven't been downloaded in the last month
- delete all but the latest 10 InedoLib, InedoIcons, and Inedo.LicenseCreator package versions that haven't been downloaded or used within the past 3 months
- delete all but the latest 5 pre-release packages that haven't been downloaded in the last month
Delete Entity
Deletes a specified entity-type
with an existing name entity-name
.
URL Format:
POST/DELETE /api/management/«entity-type»/delete/«entity-name»
Response Codes:
Code | Description |
---|---|
200 |
Success (deleted) |
403 |
Invalid/unauthorized API key, or impersonated user not granted Feeds_Manage privilege |
404 |
Entity entity-name does not exist |
Examples:
POST/PATCH /api/management/connectors/delete/OldConnector
Header | Value |
---|---|
X-ApiKey |
secure123 |
Body:
No content
PowerShell Example:
Invoke-RestMethod -Method DELETE `
-Uri http://{proget-server}/api/management/connectors/delete/OldConnector `
-Headers @{"X-ApiKey" = "secure123"}