Feature request: API to re-list a previously unlisted package

[chrisdunelm]

It's currently possible to unlist a package from nuget.org using the API, as documented here.

However, there doesn't appear to be an API to re-list a previously unlisted package.
Please can one be added?

We manage hundreds of nuget packages on nuget.org, and occasionally it's very useful to be able to programmatically unlist/relist many packages. For example, when sorting out problems caused by #5183

Thank you

[scottbommarito]

Fortunately, it's already possible, but apparently not documented.

If you hit the same url as the unlist API (https://www.nuget.org/api/v2/package/{ID}/{VERSION}) with a POST instead of a DELETE, it will re-list the package.
(https://github.com/NuGet/NuGetGallery/blob/master/src/NuGetGallery/Controllers/ApiController.cs#L590)

The same functionality exists in nuget.exe. I believe the command is "publish" and the rest of the command is the same as the unlist command ("delete").

Leaving this open because we need documentation on this. @karann-msft @anangaur

[karann-msft]

here's what happens when you try running the publish command

C:\Users\karann>nuget publish PrintHelloNuget 1.4.8 -source nuget.org -apikey <redacted>
Unknown command: 'publish'
NuGet.CommandLine.CommandLineException: Unknown command: 'publish'
   at NuGet.CommandLine.CommandManager.GetCommand(String commandName)
   at NuGet.CommandLine.CommandLineParser.ParseCommandLine(IEnumerable`1 commandLineArgs)
   at NuGet.CommandLine.Program.MainCore(String workingDirectory, String[] args)

Not a documentation issue.

Moreover, no such command shows up in nuget help

[scottbommarito]

Maybe it isn't in nuget.exe--I was pretty sure it was. In any case we are still missing the documentation for the nuget.org API.

[karann-msft]

Please create a docs issue and provide sufficient information on what needs to go into the doc. Better yet, create a PR to the docs repo :)

tagging @joelverhagen who authored this doc to understand why did we omit publish.

[chrisdunelm]

Thanks for the instant documentation :)
I'll try POSTing to the unlist URL tomorrow.

[joelverhagen]

It is undocumented because it is not part of the official protocol, meaning the official NuGet client does not use it. Also, it is unclear whether other server implementations support it (I haven't tried). As @scottbommarito mentioned, the POST /api/v2/package/{ID}/{VERSION} endpoint is implemented on NuGet.org but again this is not officially supported endpoint (e.g. push or unlist are "officially supported").

@chrisdunelm, feel free to use the endpoint right now (via a custom script). It is unlikely that we will remove or change this endpoint because a) our end-to-end tests use it to test the unlist/relist flow and b) other people are using it. If changes do sometime occur to any publicly accessibly endpoint, we will announce it via the NuGet/Announcements repository.

Also, I would recommend creating an issue on NuGet/Home if you are interested in getting official support for this feature into the NuGet client.

I would be happy to document it after talking to the team and agreeing this is something we want to officially support. Thoughts, @skofman1 @xavierdecoster?

[anangaur]

Typically we have not seen authors re-listing many packages together but seems like a general scenario for enterprises including Microsoft/.NET teams
@chrisdunelm Do you unlist all packages by default upon uploading and on a given day (coinciding with some release) re-list all packages to make them available?

I think it makes sense to have a nuget.exe command to re-list package.

[chrisdunelm]

The POST worked fine. Thanks for suggesting it.
I would ask that, if possible, this is made part of the official protocol. I agree it's not a common requirement, but there will be occasions where it's very useful.

@anangaur No, we just nuget push and allow packages to become live as nuget.org indexes them. Our release times haven't been critical enough to need to be any more precise than this. Pushing all packages generally takes about an hour.
We do have some inter-package dependencies, but up until now the packages have become live on nuget.org fast enough that we've never seen a problem.

However, due to the problem that caused #5183, we had many packages that were live on nuget.org, but a common dependency was not live. So yesterday I programmatically unlisted all of the latest version of all packages; then today programmatically relisted them all. Being able to do this using the POST request was extremely useful.

(We also have had a number of occasions where we've released many packages containing a bug; and needed to unlist them all. This isn't relevant for the relist discussion though as these bug-ridden packages never need re-listing)

[skofman1]

@joelverhagen , agree we should document this endpoint.
Created an issue for client to track the suggestion to add a "publish" command: NuGet/Home#6329

[skofman1]

Documentation was updated. Closing.

[joelverhagen]

Waiting for deployment.

[chrisdunelm]

Docs look good: https://docs.microsoft.com/en-us/nuget/api/package-publish-resource#relist-a-package
Thanks very much :)

[maartenba]

Thanks for getting the docs out! (Note the docs say a 204 is returned, but code returns an EmptyResult() which writes a regular 200)

(and even though it was apparently already in the code base would have been nice to get a heads up on this in the announcements repo)

[joelverhagen]

@maartenba, great feedback, thanks.

Concerning the 204 vs. 200 -- nice catch. I made a bad assumption about EmptyResult. I'll fix that.

Concerning the announcement -- yeah, good idea. @anangaur, could we make an announcement about this? This endpoint has been around for ages but we just now made it visible by documenting it in the API docs. We can work on the wordcraft tomorrow.