Nugetgallery: Provide simple JSON endpoint of releases nuget.exe versions

[joelverhagen]

This is a requirement coming from VSTS.

1. A list of nuget.exe versions that is only appended to. Versions never should not be removed.
2. This file should be machine readable – JSON file is the clear candidate.
3. A version string and download URL for each nuget.exe version.
4. The list of versions should be updated at the same time as the dist.nuget.org page
   a. Vsts should likely be able to test out v 4.x after it is posted to DIST, but before it is posted to that page – for partner signoff testing, etc…

/cc @rrelyea

The shape of the JSON is up to us but should be more minimal than:
http://dist.nuget.org/index.json

One proposal:

[
    {
        "version": "4.0.0-rc4",
        "url": "https://dist.nuget.org/win-x86-commandline/v4.0.0-rc4/nuget.exe"
    },
    {
        "version": "3.5.0",
        "url": "https://dist.nuget.org/win-x86-commandline/v3.5.0/nuget.exe"
    },
    {
        "version": "3.4.4",
        "url": "https://dist.nuget.org/win-x86-commandline/v3.4.4/nuget.exe"
    },
    {
        "version": "3.3.0",
        "url": "https://dist.nuget.org/win-x86-commandline/v3.3.0/nuget.exe"
    },
    {
        "version": "3.2.0",
        "url": "https://dist.nuget.org/win-x86-commandline/v3.2.0/nuget.exe"
    },
    {
        "version": "2.8.6",
        "url": "https://dist.nuget.org/win-x86-commandline/v2.8.6/nuget.exe"
    }
]

[scottbommarito]

(The major reason why http://dist.nuget.org/index.json isn't sufficient is that it only shows the last 7 or so versions and omits older versions.)

[joelverhagen]

index.json is a view concern. I don't want people coupled to that. We should be able to change it freely given it was never a supported contract.

[joelverhagen]

Spoke to @rrelyea offline and decided we could broaden this for more consumers:

{
    "nuget.exe": [
        {
            "version": "4.0.0",
            "url": "https://dist.nuget.org/win-x86-commandline/v4.0.0/nuget.exe",
            "stage": "Released",
            "uploaded": "2017-03-03T09:30:00.0000000-08:00"
        },
        {
            "version": "3.5.0",
            "url": "https://dist.nuget.org/win-x86-commandline/v3.5.0/nuget.exe",
            "stage": "ReleasedAndBlessed",
            "uploaded": "2016-12-19T15:30:00.0000000-08:00"
        },
        {
            "version": "3.4.4",
            "url": "https://dist.nuget.org/win-x86-commandline/v3.4.4/nuget.exe",
            "stage": "ReleasedAndBlessed",
            "uploaded": "2016-12-19T15:30:00.0000000-08:00"
        },
        {
            "version": "3.3.0",
            "url": "https://dist.nuget.org/win-x86-commandline/v3.3.0/nuget.exe",
            "stage": "ReleasedAndBlessed",
            "uploaded": "2016-02-22T14:30:00.0000000-08:00"
        },
        {
            "version": "3.2.0",
            "url": "https://dist.nuget.org/win-x86-commandline/v3.2.0/nuget.exe",
            "stage": "ReleasedAndBlessed",
            "uploaded": "2015-09-16T14:00:00.0000000-07:00"
        },
        {
            "version": "2.8.6",
            "url": "https://dist.nuget.org/win-x86-commandline/v2.8.6/nuget.exe",
            "stage": "ReleasedAndBlessed",
            "uploaded": "2015-09-01T12:30:00.0000000-07:00"
        }
    ]
}

Schema

{
  "title": "NuGet Tool Versions",
  "description": "The schema for versions of nuget.exe available on the download site.",
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "nuget.exe": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "version": {
            "description": "The Semantic Version string of the tool. Regex from https://github.com/mojombo/semver/issues/232.",
            "type": "string",
            "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(-(0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(\\.(0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*)?(\\+[0-9a-zA-Z-]+(\\.[0-9a-zA-Z-]+)*)?$"
          },
          "url": {
            "description": "The absolute URL to download this version of the tool.",
            "type": "string"
          },
          "stage": {
            "description": "An enum to describe just how vetted this version of the tool is. 'ValidationOngoingNotFinalRelease' versions are not yet visible on the download site and should be validated by partners.\\n'Released' has been made available on the download site but is not yet recommended for wide-spread consumption.\\n'ReleasedAndBlessed' has been made available on the download site and is recommended for consumption.",
            "type": "string",
            "enum": [
              "ValidationOngoingNotFinalRelease",
              "Released",
              "ReleasedAndBlessed"
            ]
          },
          "uploaded": {
            "description": "The ISO-8601 time when the version was uploaded.",
            "type": "string",
            "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}.\\d{7}([\\-\\+]\\d{2}:\\d{2}|Z)$"
          }
        }
      }
    }
  }
}

[maartenba]

Perhaps reuse the json document that powers dist.nuget.org? New API keep popping up daily it seems.

[joelverhagen]

Perhaps reuse the json document that powers dist.nuget.org? New API keep popping up daily it seems.

I wouldn't consider this API part of V2 or V3. The only purpose here is to communicate released nuget.exe versions.

Concerning the existing JSON document on dist.nuget.org, that is a view concern where versions are periodically removed. VSTS wants a document where versions are not removed.

[maartenba]

Would still be cool to have it documented though. TeamCity, AppVeyor, MyGet, Travis, Jenkins, ... could benefit from this API too.

[joelverhagen]

This data is now available here:
http://dist.nuget.org/tools.json

This is a better alternative to http://dist.nuget.org/index.json.