ProGet Documentation

Feed Management API

  • Last Modified: 2019-05-07

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 is created first. This key can be supplied 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

PropertyDetails
name*string - the unique name of the feed; must not include 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
descriptionstring - a description displayed with the ProGet feed name in the UI; supplying null removes the description
activeboolean - indicates whether the feed is active (true) or disabled (false)
cacheConnectorsboolean - indicates whether connector caching is enabled for the feed
dropPathstring - disk path accessible to ProGet's service where packages may be added to the feed; supplying null disables the drop path
packagesPathstring - 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
packageStorestring - 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
allowUnknownLicensesboolean - indicates whether packages with "unknown" licenses are allowed; supplying null will inherit the value of the Feeds.AllowUnknownLicenseDownloads setting
allowedLicensesstring[] - 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
blockedLicensesstring[] - 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
symbolServerEnabledboolean - indicates whether the NuGet symbol server is enabled; only applies to NuGet-like feed types
stripSymbolsboolean - indicates whether symbol files (i.e. .pdb files) are removed from a NuGet-like package when downloaded
stripSourceboolean - indicates whether source files (i.e. files under src/ in the package) are removed from a NuGet-like package when downloaded
connectorsstring[] - array of connectors for the feed; supply an empty array to remove all feed connectors
vulnerabilitySourcesstring[] - array of vulnerability sources for the feed; supply an empty array to remove all vulnerability sources
retentionRulesRetentionObject[] - 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
packageFiltersstring[] - array of serialized configurations that define the custom package filters; see Persisted XML; supply an empty array to remove all package filters
packageAccessRulesstring[] - array of serialized configurations that define the custom package access rules; see Persisted XML; supply an empty array to remove all package access rules
replicationReplicationObject - a replication object that defines the replication configuration for the feed
variablesobject - 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:
  • a variable name is a string of no more than fifty characters: numbers (0-9), upper- and lower-case letters (a-Z), dashes (-), spaces ( ), and underscores (_) and must start with a letter, and may not start or end with a dash, underscore, or space
  • a variable value is a string of any number of characters

Connector Data Model

PropertyDetails
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
urlstring - the URL of the connector
usernamestring - the username used for authentication at the connector URL
passwordstring - the password used for authentication at the connector URL
timeoutinteger - the timeout (in seconds) used when making a request to the connector URL
filtersstring[] - array of connector filters; supply an empty array to remove all filters; supports wildcards and negations
metadataCacheEnabledboolean - indicates whether metadata caching is enabled on the connector
metadataCacheMinutesinteger - the number of minutes a connector metadata request to a specific URL is cached by ProGet (default: 30)
metadataCacheCountinteger - 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.

PropertyDetails
deletePrereleaseVersionsboolean - 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)
deleteCachedboolean - when true, the retention rule only applies to cached connector packages
keepVersionsCountinteger - when set to n, the retention rule always keeps the latest n versions of a matching package; this value is ignored for Docker feeds
keepUsedWithinDaysinteger - when set to n, the retention rule always keeps package versions if they have been downloaded within the past n days
triggerDownloadCountinteger - when set to n, the retention rule always keeps versions that have been downloaded more than n times
keepPackageIdsstring[] - array of package names/identifiers that are kept regardless of other filters; supports wildcards but not negations, as any matching package is always kept
deletePackageIdsstring[] - array of package names/identifiers that are deleted if they match all other filters; supports wildcards but not negations (use keepPackageIds for exclusions)
keepVersionsstring[] - array of package versions that are kept regardless of other filters; supports wildcards but not negations, as any matching package version is always kept
deleteVersionsstring[] - array of package versions that are deleted if they match all other filters; supports wildcards but not negations (use keepVersions for exclusions)
sizeTriggerKbinteger - 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
sizeExclusiveboolean - 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 this is only used within a feed entity's replication property.

PropertyDetails
clientModestring - the client replication mode configuration, one of disabled, pullonly, pushonly, mirror; more info
serverModestring - the server replication mode configuration, one of disabled, readonly, writeonly, readwrite; more info
clientTokenstring - 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
serverTokenstring - 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
sourceUrlstring - the URL of the replication server; this field is required when clientMode is set to anything other than disabled

License Data Model

PropertyDetails
licenseId*string - an SPDX license identifier
titlestring - a friendly name for the license
urlsstring[] - array of URLs used to map a package license to SPDX identifer
allowedboolean - indicates whether a license is allowed (true) or blocked (false) at the global level
allowedFeedsstring[] - array of feed names that contain a license rule set to allow the license
blockedFeedsstring[] - array of feed names that contain a license rule set to block the license

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. or Castle.*
  • excludes any packages that start with Rubbishsoft.

Feed & Package Types

In the ProGet UI, Chocolatey and PowerShell are represented as separate feed types, even though they just contain NuGet packages and use the same NuGet API. This is why, in the ProGet UI, you can change a feed's type 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 and romp
  • nuget, chocolatey, and powershell

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
  • Azure Blob Storage
  • Custom Extension Format
<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>
<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>
<{FullNamespace.ClassName} Assembly="AssemblyName">
  <Properties PropertyNameA="{property value}" PropertyNameB="1000" />
</{FullNamespace.ClassName}>

Names & IDs

Because one of the primary use cases of the Feed Management API is maintaining feed configuration across instances of ProGet, using or exposing the read-only, system-generated identifiers for entities is not practical. As such, these IDs are not used by the API.

Default Feed Disk Path

When you don't specify a disk path for a feed to use, ProGet will use a path that's based on the feed's system-generated ID. This means that, just like in the UI, if were to 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 of feeds, connectors, or licenses
  • action-type is one of list, get, create, update, or delete
  • entity-name is the name identifier of the entity being updated, or deleted; it is not valid on a list or create 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 readability
  • application/json content type is required for any data sent via POST/PUT/PATCH

List Entities

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:
CodeDescription
200Success
403Invalid/unauthorized API key, or impersonated user not granted Feeds_Manage privilege
Example Responses:
  • List Feeds
  • List Connectors
  • List Licenses

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 Den",
    "url": "https://inedo.com/den/feed",
    "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

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:
CodeDescription
200Success
403Invalid/unauthorized API key, or impersonated user not granted Feeds_Manage privilege
404Entity not found
Example Responses:
  • Get Feed
  • Get Connector
  • Get License

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 Den",
  "url": "https://inedo.com/den/feed",
  "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

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:
CodeDescription
201Success (created); response body contains new object
400Validation error; the response body content will contain specific error messages e.g. "feed name is required", "invalid feed type"
403Invalid/unauthorized API key, or impersonated user not granted Feeds_Manage privilege
422Invalid 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:
  • Create Simple Feed

POST/PUT /api/management/feeds/create

HeaderValue
X-ApiKeysecure123
Content-Typeapplication/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

Updates a specified entity-type with an existing name entity-name using the properties defined in the body of the request. 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:
CodeDescription
201Success (updated); response body contains updated object
400Validation error; the response body content will contain specific error messages e.g. "feed name is required", "invalid feed type"
403Invalid/unauthorized API key, or impersonated user not granted Feeds_Manage privilege
404Entity entity-name does not exist
422Invalid 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:
  • Add Feed Description
  • Update Connector URL
  • Configure Retention

POST/PATCH /api/management/feeds/update/InedoExtensions

HeaderValue
X-ApiKeysecure123
Content-Typeapplication/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

HeaderValue
X-ApiKeysecure123
Content-Typeapplication/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

HeaderValue
X-ApiKeysecure123
Content-Typeapplication/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 prerelease 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:
CodeDescription
200Success (deleted)
403Invalid/unauthorized API key, or impersonated user not granted Feeds_Manage privilege
404Entity entity-name does not exist
Examples:
  • Delete Connector

POST/PATCH /api/management/connectors/delete/OldConnector

HeaderValue
X-ApiKeysecure123

Body:

No content


PowerShell Example:

Invoke-RestMethod -Method DELETE `
  -Uri http://{proget-server}/api/management/connectors/delete/OldConnector `
  -Headers @{"X-ApiKey" = "secure123"}

Is this documentation incorrect or incomplete? Help us by contributing!

This documentation is licensed under CC-BY-SA-4.0 and stored in GitHub.