Query Package Promotions Endpoint
  • 18 Dec 2023
  • 3 Minutes to read
  • Dark
    Light
  • PDF

Query Package Promotions Endpoint

  • Dark
    Light
  • PDF

Article Summary

The Query Package Promotions is an endpoint to return a JSON array of PromotedPackage objects describing the status of promoted packages.

šŸš€ Quick Example: Querying with Curl

This example queries a promoted package (myNugetPackage, version 1.2.3) from one feed (nuget-unapproved) to another (nuget-approved), authenticating with the API key abc12345:

curl -X GET --header "X-ApiKey: abc12345" "http://54.168.224.223:8624/api/promotions/list?package=Newtonsoft.Json&version=13.0.2"

Authentication and API Keys

The following is a summary of access types and their corresponding requirements for various API keys types and endpoints within this API.

An API Key is not required to query package promotions.

When an API Key isn't specified, and the Anonymous user doesn't have "Feeds: View Feed" access, then a 401 authentication challenge will be issued. Otherwise, only the promotions the Anonymous user has access to view will be displayed.

Access TypeRequirements
System API KeysUse/Manage Feeds
Feed API KeysView/Download
Personal API KeyFeeds_ViewFeed
No API Keyanonymous 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.

Request Specification

To query the status of promoted packages, simply GET to the URL with querystring parameters and an appropriate API Key.

You may filter the results by specifying one or more parameters:

ArgumentDetails
fromFeedthe feed that the package was promoted from
toFeedthe feed that the package was promoted to
groupused only by Universal and npm feeds; for npm, this is the "scope"
packagethe package name of the promoted package
versionthe version of the promoted package
GET /api/promotions/list/fromFeed=Ā«feed-nameĀ»&toFeed=Ā«feed-nameĀ»&group=Ā«group-nameĀ»&package=Ā«package-nameĀ»&version=Ā«versionĀ»

Querying a specific promoted NuGet package requires the package name (e.g. myNugetPackage), the version (e.g. 1.2.3), the feed promoted from (e.g. nuget-unapproved) and the feed promoted to (e.g. nuget-approved)

GET /api/promotions/list?fromFeed=npm-development&toFeed=npm-production&group=myScope&package=myNpmPackage&version=1.2.3

Response Specification

A successful (200) response body will contain an array of PromotedPackage objects. For example, querying version 1.2.3 of myNugetPackage, promoted from feed nuget-unapproved to feed nuget-approved return a single object:

GET /api/promotions/list?fromFeed=nuget-unapproved&toFeed=nuget-unapproved&package=myNugetPackage&version=1.2.3

[
  {
    "packageName": "myNugetPackage",
    "packageType": "nuget",
    "version": "1.2.3",
    "promotions": [
          {
          "fromFeed": "nuget-unapproved",
          "toFeed": "nuget-approved",
          "date": "2023-11-28T06:23:46.92Z",
          "user": "Anonymous",
          "comments": "",
          "id": 4
          }
  ]
  },
]
ResponseDetails
200 (Success)body will contain an array of PromotedPackage objects
400 (Invalid Input)indicates invalid or missing properties on the package; the body will provide some details as text
403 (Unauthorized API Key)indicates a missing, unknown, or unauthorized API Key; the body will be empty

Data Specifications

PromotedPackage is a set of key/value pairs used as output data for the Query Promoted Package endpoint as a JSON-formatted object.

PropertyFormatNotes
groupstringrepresenting the name or ID of the package.
packagestringrepresenting the group of the package for Universal and Maven feeds and the scope of the package for npm feeds. This property is omitted for all other feed types.
packageTypestringrepresenting the feed type of the package, one of: upack, powershell, nuget, chocolatey, maven, npm, bower, or docker
versionstringrepresenting the version of the package. In ProGet 5.0.9 and later, you can specify latest or latest-stable for the version property. This will then promote the latest or latest non-prerelease version of the package.
promotionsarrayAn array of PromotionData objects representing package promotions.

JSON Object:

{
  "group": "myScope",
  "package": "myPackage",
  "packageType": "npm",
  "version": "1.0.0",
  "promotions": [
    {
      "fromFeed": "npm-unapproved",
      "toFeed": "npm-approved",
      "date": "2023-11-29T12:00:00",
      "user": "jsmith",
      "comments": "Package approved for production use",
      "id": 12345
    }
  ]
}

PromotionData Object Attributes

PromotionDatais a subset of attributes on the PromotedPackage Object that provide details of an individual promotion, used as output data for the Query Promoted Package endpoint.

PropertyFormatNotes
fromFeedstringrepresenting the name of the feed the promotion originated from.
toFeedstringrepresenting the name of the feed the package was promoted to.
datestringrepresenting the UTC date of the promotion in ISO 8601 format (yyyy-MM-ddThh:mm:ss).
userstringrepresenting the user who promoted the package. Packages promoted via this API will by noted with SYSTEM as the user.
commentsstringcontaining comments submitted when the promotion occurred.
idintrepresenting a unique identifier of the promotion.

JSON Object:

{
  "fromFeed": "npm-unapproved",
  "toFeed": "npm-approved",
  "date": "2023-11-29T12:00:00",
  "user": "jsmith",
  "comments": "Package approved for production use",
  "id": 12345
}

Was this article helpful?