From ec39293987abb09f55214ddd83ced66c554a4582 Mon Sep 17 00:00:00 2001 From: Joel Verhagen Date: Fri, 9 Dec 2022 10:51:17 -0500 Subject: [PATCH 1/7] Add API docs for the deprecation API (public preview) --- docs/api/package-publish-resource.md | 69 +++++++++++++++++++++++++--- docs/api/rate-limits.md | 8 ++-- 2 files changed, 68 insertions(+), 9 deletions(-) diff --git a/docs/api/package-publish-resource.md b/docs/api/package-publish-resource.md index 57ffa8e46..cdc0529ce 100644 --- a/docs/api/package-publish-resource.md +++ b/docs/api/package-publish-resource.md @@ -1,6 +1,6 @@ --- title: Push and Delete, NuGet API -description: The publish service allows clients to publish new packages and unlist or delete existing packages. +description: The publish service allows clients to publish new packages, unlist/delete, or deprecate existing packages. author: joelverhagen ms.author: jver ms.date: 10/26/2017 @@ -17,13 +17,14 @@ V3 API. These operations are based off of the `PackagePublish` resource found in The following `@type` value is used: -@type value | Notes --------------------- | ----- -PackagePublish/2.0.0 | The initial release +@type value | Notes +------------------------------ | ----- +PackagePublish/2.0.0 | The initial release +PackagePublish/3.0.0-preview.1 | Include support for deprecating packages (**contract may change in the future**) ## Base URL -The base URL for the following APIs is the value of the `@id` property of the `PackagePublish/2.0.0` resource in the +The base URL for the following APIs is the value of the `@id` property of the `PackagePublish` resource in the package source's [service index](service-index.md). For the documentation below, nuget.org's URL is used. Consider `https://www.nuget.org/api/v2/package` as a placeholder for the `@id` value found in the service index. @@ -76,7 +77,7 @@ Status Code | Meaning Server implementations vary on the success status code returned when a package is successfully pushed. -## Delete a package +## Delete (or unlist) a package nuget.org interprets the package delete request as an "unlist". This means that the package is still available for existing consumers of the package but the package no longer appears in search results or in the web interface. For @@ -131,3 +132,59 @@ Status Code | Meaning ----------- | ------- 200 | The package is now listed 404 | No package with the provided `ID` and `VERSION` exists + +## Deprecate or undeprecate a package + +> [!Note] +> This API is currently in public preview. The API contract may change in the future. To ensure the package source still supports this contract, verify the `PackagePublish/3.0.0-preview.1` resource is listed in the [service index](service-index.md). +> For NuGet.org, create an API key with the ability to **unlist**. This is the scope checked for this operation. + +A package can be marked as deprecated or have deprecation details modified and removed using this endpoint. This endpoint uses the `PUT` HTTP method and expects a JSON request body. + +If the package already has deprecation details matching the request body, the request still succeeds. + +To mark a package as deprecated, set one or more of `isLegacy`, `hasCriticalBugs`, or `isOther` (generally called deprecation statuses) to `true`. To undeprecate a package (i.e. remove deprecation details), exclude the deprecation status booleans from the request body allowing them to default to `false`. You can explicitly set all of the deprecation status booleans to false but this to undeprecate but this approach may not be forward compatible. + +For more information on the user experience of package deprecation, see [deprecating packages](../nuget-org/Deprecate-packages.md). + +``` +PUT https://www.nuget.org/api/v2/package/{ID}/deprecations +``` + +### Request parameters + +Name | In | Type | Required | Notes +----------------------- | ------------ | ------ | -------- | ----- +ID | URL | string | yes | The ID of the package to modify deprecation information on +X-NuGet-ApiKey | Header | string | yes | For example, `X-NuGet-ApiKey: {USER_API_KEY}` +User-Agent | Header | string | yes | A user agent string is required, include a URL to your project if possible, e.g. `Spoon-Knife/1.0.0 (+https://github.com/octocat/Spoon-Knife)` +versions | Request body | array of strings | yes | The package versions to apply the provided deprecation details to +isLegacy | Request body | boolean | no | If set to true, mark the package version(s) as legacy, defaults to false +hasCriticalBugs | Request body | boolean | no | If set to true, mark the package version(s) as having critical bugs, defaults to false +isOther | Request body | boolean | no | If set to true, mark the package version(s) as having some other deprecation reason, defaults to false +alternatePackageId | Request body | string | no | An alternate package ID to refer package consumer to, in lieu of this package +alternatePackageVersion | Request body | string | no | A specific version for the alternate package ID +message | Request body | string | no | A user-facing, plain text message to include with the other deprecation details, required if `isOther` is true. + +### Response + +Status Code | Meaning +----------- | ------- +200 | The package deprecation information has been successfully modified +400 | The request is invalid, check the HTTP reason phrase for details +404 | No package with the provided `ID`, `versions`, or alternate package does not exist + +### Sample request + +``` +PUT https://www.nuget.org/api/v2/package/NuGet.Core/deprecations +X-NuGet-ApiKey: {USER_API_KEY} + +{ + "versions": [ "2.12.0" ], + "isLegacy": true, + "alternatePackageId": "NuGet.Protocol", + "alternatePackageVersion": "6.4.0", + "message": "NuGet.Core has been replaced by NuGet client v3 and later APIs." +} +``` diff --git a/docs/api/rate-limits.md b/docs/api/rate-limits.md index f738504b6..8418b6d0f 100644 --- a/docs/api/rate-limits.md +++ b/docs/api/rate-limits.md @@ -45,12 +45,14 @@ The following tables list the rate limits for the NuGet.org API. **GET** `/api/v2/Packages` | IP | 20000 / minute | Query NuGet package metadata via v2 OData `Packages` collection | **GET** `/api/v2/Packages/$count` | IP | 100 / minute | Query NuGet package count via v2 OData `Packages` collection | -## Package Push and Unlist +## Package Push, unlist, relist, and set deprecation details | API | Limit Type | Limit Value | API Use Case | |:---|:---|:---|:--- | -**PUT** `/api/v2/package` | API Key | 350 / hour | Upload a new NuGet package (version) via v2 push endpoint -**DELETE** `/api/v2/package/{id}/{version}` | API Key | 250 / hour | Unlist a NuGet package (version) via v2 endpoint +**PUT** `/api/v2/package` | API Key | 350 / hour | Upload a new NuGet package (version) via package publish endpoint +**DELETE** `/api/v2/package/{id}/{version}` | API Key | 250 / hour | Unlist a NuGet package (version) via package publish endpoint +**POST** `/api/v2/package/{id}/{version}` | API Key | 250 / hour | Relist a NuGet package (version) via package publish endpoint +**PUT** `/api/v2/package/{id}/deprecations` on multiple version | API Key | 1 / minute | Update the deprecation information on multiple package versions ## nuget.org website page views From ac57d8c762316b2ddd21582b999aa370beebe641 Mon Sep 17 00:00:00 2001 From: Joel Verhagen Date: Fri, 9 Dec 2022 11:05:16 -0500 Subject: [PATCH 2/7] Fix up --- docs/api/package-publish-resource.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/package-publish-resource.md b/docs/api/package-publish-resource.md index cdc0529ce..e2132e05f 100644 --- a/docs/api/package-publish-resource.md +++ b/docs/api/package-publish-resource.md @@ -157,7 +157,7 @@ Name | In | Type | Required | Notes ----------------------- | ------------ | ------ | -------- | ----- ID | URL | string | yes | The ID of the package to modify deprecation information on X-NuGet-ApiKey | Header | string | yes | For example, `X-NuGet-ApiKey: {USER_API_KEY}` -User-Agent | Header | string | yes | A user agent string is required, include a URL to your project if possible, e.g. `Spoon-Knife/1.0.0 (+https://github.com/octocat/Spoon-Knife)` +User-Agent | Header | string | yes | A user agent string is required, optionally include a URL to your project if possible, e.g. `Spoon-Knife/1.0.0 (+https://github.com/octocat/Spoon-Knife)` versions | Request body | array of strings | yes | The package versions to apply the provided deprecation details to isLegacy | Request body | boolean | no | If set to true, mark the package version(s) as legacy, defaults to false hasCriticalBugs | Request body | boolean | no | If set to true, mark the package version(s) as having critical bugs, defaults to false From a7961f1b46750b27adccd12a99e8870490614424 Mon Sep 17 00:00:00 2001 From: Joel Verhagen Date: Fri, 9 Dec 2022 11:14:39 -0500 Subject: [PATCH 3/7] Fix some stuff, clarify TOC --- docs/TOC.md | 2 +- docs/api/package-publish-resource.md | 10 ++++++---- 2 files changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/TOC.md b/docs/TOC.md index 1ee1c9177..f79155161 100644 --- a/docs/TOC.md +++ b/docs/TOC.md @@ -122,7 +122,7 @@ #### [Package content](api/package-base-address-resource.md) #### [Package details URL](api/package-details-template-resource.md) #### [Package metadata](api/registration-base-url-resource.md) -#### [Push and delete](api/package-publish-resource.md) +#### [Update packages](api/package-publish-resource.md) #### [Push symbol packages](api/symbol-package-publish-resource.md) #### [Report abuse URL](api/report-abuse-resource.md) #### [Repository signatures](api/repository-signatures-resource.md) diff --git a/docs/api/package-publish-resource.md b/docs/api/package-publish-resource.md index e2132e05f..528009a82 100644 --- a/docs/api/package-publish-resource.md +++ b/docs/api/package-publish-resource.md @@ -1,5 +1,5 @@ --- -title: Push and Delete, NuGet API +title: Update Packages, NuGet API description: The publish service allows clients to publish new packages, unlist/delete, or deprecate existing packages. author: joelverhagen ms.author: jver @@ -8,11 +8,13 @@ ms.topic: reference ms.reviewer: kraigb --- -# Push and Delete +# Push, delete/unlist, relist, deprecate It is possible to push, delete (or unlist, depending on the server implementation), and relist packages using the NuGet V3 API. These operations are based off of the `PackagePublish` resource found in the [service index](service-index.md). +Many package feeds do not allow the modification of existing package content. However some metadata about a package can be modified after upload, e.g. listed status and deprecation information. Please refer to documentation for your specific package source as needed. This document generally describes generic behavior and behavior on nuget.org. + ## Versioning The following `@type` value is used: @@ -109,7 +111,7 @@ Status Code | Meaning ## Relist a package If a package is unlisted, it is possible to make that package once again visible in search results using the "relist" -endpoint. This endpoint has the same shape as the [delete (unlist) endpoint](#delete-a-package) but uses the `POST` +endpoint. This endpoint has the same shape as the [delete (unlist) endpoint](#delete-or-unlist-a-package) but uses the `POST` HTTP method instead of the `DELETE` method. If the package is already listed, the request still succeeds. @@ -137,7 +139,7 @@ Status Code | Meaning > [!Note] > This API is currently in public preview. The API contract may change in the future. To ensure the package source still supports this contract, verify the `PackagePublish/3.0.0-preview.1` resource is listed in the [service index](service-index.md). -> For NuGet.org, create an API key with the ability to **unlist**. This is the scope checked for this operation. +> For nuget.org, create an API key with the ability to **unlist**. This is the scope checked for this operation. A package can be marked as deprecated or have deprecation details modified and removed using this endpoint. This endpoint uses the `PUT` HTTP method and expects a JSON request body. From aede829ab6e8b218befd7fd6133b13329e70e239 Mon Sep 17 00:00:00 2001 From: Joel Verhagen Date: Fri, 9 Dec 2022 11:22:48 -0500 Subject: [PATCH 4/7] Fix notices --- docs/api/package-publish-resource.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/api/package-publish-resource.md b/docs/api/package-publish-resource.md index 528009a82..f0cf9cf9a 100644 --- a/docs/api/package-publish-resource.md +++ b/docs/api/package-publish-resource.md @@ -137,8 +137,10 @@ Status Code | Meaning ## Deprecate or undeprecate a package -> [!Note] +> [!Warning] > This API is currently in public preview. The API contract may change in the future. To ensure the package source still supports this contract, verify the `PackagePublish/3.0.0-preview.1` resource is listed in the [service index](service-index.md). + +> [!Note] > For nuget.org, create an API key with the ability to **unlist**. This is the scope checked for this operation. A package can be marked as deprecated or have deprecation details modified and removed using this endpoint. This endpoint uses the `PUT` HTTP method and expects a JSON request body. From c63cfc3d91e1c39fa4ef0764f74c19c9856591b6 Mon Sep 17 00:00:00 2001 From: Joel Verhagen Date: Tue, 23 Apr 2024 16:08:40 -0400 Subject: [PATCH 5/7] Update docs --- docs/api/package-publish-resource.md | 32 +++++++++++++++++++++++++--- 1 file changed, 29 insertions(+), 3 deletions(-) diff --git a/docs/api/package-publish-resource.md b/docs/api/package-publish-resource.md index f0cf9cf9a..e84001465 100644 --- a/docs/api/package-publish-resource.md +++ b/docs/api/package-publish-resource.md @@ -147,7 +147,11 @@ A package can be marked as deprecated or have deprecation details modified and r If the package already has deprecation details matching the request body, the request still succeeds. -To mark a package as deprecated, set one or more of `isLegacy`, `hasCriticalBugs`, or `isOther` (generally called deprecation statuses) to `true`. To undeprecate a package (i.e. remove deprecation details), exclude the deprecation status booleans from the request body allowing them to default to `false`. You can explicitly set all of the deprecation status booleans to false but this to undeprecate but this approach may not be forward compatible. +To mark a package as deprecated, set one or more of `isLegacy`, `hasCriticalBugs`, or `isOther` (generally called deprecation statuses or deprecation reasons) to `true`. To undeprecate a package (i.e. remove deprecation details), exclude all of the deprecation status booleans from the request body allowing them to default to `false`. + +A request body with only the required `versions` property will remove any deprecation information from all specified versions, since the deprecation status (reason) booleans default to `false`. + +You can mark the versions as unlisted at the same time by including the `listedVerb` property set to the `Unlist` string. For more information on the user experience of package deprecation, see [deprecating packages](../nuget-org/Deprecate-packages.md). @@ -166,9 +170,10 @@ versions | Request body | array of strings | yes | The packa isLegacy | Request body | boolean | no | If set to true, mark the package version(s) as legacy, defaults to false hasCriticalBugs | Request body | boolean | no | If set to true, mark the package version(s) as having critical bugs, defaults to false isOther | Request body | boolean | no | If set to true, mark the package version(s) as having some other deprecation reason, defaults to false -alternatePackageId | Request body | string | no | An alternate package ID to refer package consumer to, in lieu of this package +alternatePackageId | Request body | string | no | An alternate package ID to refer package consumer to, in lieu of this package, required if `alternatePackageVersion` is specified alternatePackageVersion | Request body | string | no | A specific version for the alternate package ID -message | Request body | string | no | A user-facing, plain text message to include with the other deprecation details, required if `isOther` is true. +message | Request body | string | no | A user-facing, plain text message to include with the other deprecation details, required if `isOther` is true +listedVerb | Request body | string | no | Changes the listed status with `Unlist` (mark all specified versions as unlisted), `Relist` (mark all specified versions as listed), or `Unchanged` (leave listed status as-is), defaults to `Unchanged` ### Response @@ -180,8 +185,11 @@ Status Code | Meaning ### Sample request +This request marks NuGet.Core 2.12.0 as deprecated with the "Legacy" reason. The NuGet.Protocol 6.4.0 package is used as the alternate package. + ``` PUT https://www.nuget.org/api/v2/package/NuGet.Core/deprecations +User-Agent: Spoon-Knife/1.0.0 X-NuGet-ApiKey: {USER_API_KEY} { @@ -192,3 +200,21 @@ X-NuGet-ApiKey: {USER_API_KEY} "message": "NuGet.Core has been replaced by NuGet client v3 and later APIs." } ``` + +### Sample request + +This request marks NuGet.Core 2.12.0, 2.13.0, and 2.14.0 as deprecated with the "Legacy" and "Other" reasons displaying the provided message. All three versions will be unlisted at the same time as being marked as deprecated. + +``` +PUT https://www.nuget.org/api/v2/package/NuGet.Core/deprecations +User-Agent: Spoon-Knife/1.0.0 +X-NuGet-ApiKey: {USER_API_KEY} + +{ + "versions": [ "2.12.0", "2.13.0", "2.14.0" ], + "isLegacy": true, + "isOther": true + "message": "NuGet.Core has been replaced by NuGet client v3 and later APIs.", + "listedVerb": "Unlist" +} +``` From ed0dd5ba8ef5c30cb9c785f665d0484fd6f8ca08 Mon Sep 17 00:00:00 2001 From: Joel Verhagen Date: Tue, 23 Apr 2024 16:14:30 -0400 Subject: [PATCH 6/7] Update deprecation rate limits --- docs/api/rate-limits.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/api/rate-limits.md b/docs/api/rate-limits.md index 8418b6d0f..3862a6d0b 100644 --- a/docs/api/rate-limits.md +++ b/docs/api/rate-limits.md @@ -52,7 +52,8 @@ The following tables list the rate limits for the NuGet.org API. **PUT** `/api/v2/package` | API Key | 350 / hour | Upload a new NuGet package (version) via package publish endpoint **DELETE** `/api/v2/package/{id}/{version}` | API Key | 250 / hour | Unlist a NuGet package (version) via package publish endpoint **POST** `/api/v2/package/{id}/{version}` | API Key | 250 / hour | Relist a NuGet package (version) via package publish endpoint -**PUT** `/api/v2/package/{id}/deprecations` on multiple version | API Key | 1 / minute | Update the deprecation information on multiple package versions +**PUT** `/api/v2/package/{id}/deprecations` on multiple versions | API Key | 1 / minute | Update the deprecation information on multiple package versions +**PUT** `/api/v2/package/{id}/deprecations` on a single version | API Key | 250 / hour | Update the deprecation information on a single package version ## nuget.org website page views From d890f1ed822f0d0572f06e88677ae8cdcab3ae54 Mon Sep 17 00:00:00 2001 From: Joel Verhagen Date: Fri, 24 May 2024 10:38:54 -0400 Subject: [PATCH 7/7] Update deprecation rate limits --- docs/api/rate-limits.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/api/rate-limits.md b/docs/api/rate-limits.md index 3862a6d0b..f82ea32d8 100644 --- a/docs/api/rate-limits.md +++ b/docs/api/rate-limits.md @@ -52,8 +52,7 @@ The following tables list the rate limits for the NuGet.org API. **PUT** `/api/v2/package` | API Key | 350 / hour | Upload a new NuGet package (version) via package publish endpoint **DELETE** `/api/v2/package/{id}/{version}` | API Key | 250 / hour | Unlist a NuGet package (version) via package publish endpoint **POST** `/api/v2/package/{id}/{version}` | API Key | 250 / hour | Relist a NuGet package (version) via package publish endpoint -**PUT** `/api/v2/package/{id}/deprecations` on multiple versions | API Key | 1 / minute | Update the deprecation information on multiple package versions -**PUT** `/api/v2/package/{id}/deprecations` on a single version | API Key | 250 / hour | Update the deprecation information on a single package version +**PUT** `/api/v2/package/{id}/deprecations` | API Key | 125 versions / 5 minutes | Update the deprecation information via package publish endpoint ## nuget.org website page views