Metadados de pacote

É possível buscar metadados sobre os pacotes disponíveis em uma origem de pacote usando a API do NuGet V3. Esses metadados podem ser obtidos usando o recurso RegistrationsBaseUrl encontrado no índice de serviço.

A coleção dos documentos encontrados em RegistrationsBaseUrl são muitas vezes chamados de “registros” ou “blobs de registro”. O conjunto de documentos sob um único RegistrationsBaseUrl é chamado de “hive de registro”. Um hive de registro contém metadados sobre cada pacote disponível em uma origem do pacote.

Controle de versão

Os seguintes valores de @type são usados:

Isso representa três hives de registro distintos disponíveis para várias versões de clientes.

RegistrationsBaseUrl

Esses registros não são compactados (o que significa que eles usam um Content-Encoding: identity implícito). Os pacotes do SemVer 2.0.0 estão excluídos deste hive.

RegistrationsBaseUrl/3.4.0

Esses registros são compactados usando Content-Encoding: gzip. Os pacotes do SemVer 2.0.0 estão excluídos deste hive.

RegistrationsBaseUrl/3.6.0

Esses registros são compactados usando Content-Encoding: gzip. Os pacotes SemVer 2.0.0 estão incluídos neste hive. Para obter mais informações sobre o SemVer 2.0.0, consulte Suporte do SemVer 2.0.0 para nuget.org.

URL base

A URL base para as APIs a seguir é o valor da propriedade @id associada aos valores de @type de recurso mencionados anteriormente. No documento a seguir, a URL base {@id} do espaço reservado será usada. A URL base pode ser alterada com base na implementação ou nas alterações de infraestrutura dentro da origem do pacote, portanto, ela deve ser buscada dinamicamente no índice de serviço pelo software cliente.

Métodos HTTP

Todos os URLs encontrados no recurso de registro são compatíveis com os métodos HTTP GET e HEAD.

Índice de registro

Os grupos de recursos de registro empacotam metadados por ID do pacote. Não é possível obter dados sobre mais de uma ID de pacote ao mesmo tempo. Esse recurso não fornece nenhuma maneira de descobrir IDs de pacote. Em vez disso, presume-se que o cliente já saiba a ID do pacote desejado. Os metadados disponíveis sobre cada versão do pacote variam de acordo com a implementação do servidor. Os blobs de registro de pacote têm a seguinte estrutura hierárquica:

• Índice: o ponto de entrada para os metadados do pacote, compartilhado por todos os pacotes em uma origem com a mesma ID de pacote.
• Página: um agrupamento de versões de pacotes. O número de versões de pacote em uma página é definido pela implementação do servidor.
• Folha: um documento específico para uma única versão do pacote.

A URL do índice de registro é previsível e pode ser determinada pelo cliente que recebe uma ID de pacote e o valor de @id do recurso de registro do índice de serviço. As URLs das páginas e folhas de registro são descobertas inspecionando o índice de registro.

Páginas e folhas de registro

Embora não seja estritamente necessário para uma implementação de servidor armazenar folhas de registro em documentos de página de registro separados, é uma prática recomendada para conservar a memória do lado do cliente. Em vez de embutir todas as folhas de registro no índice ou armazenar imediatamente as folhas em documentos de página, é recomendável que a implementação do servidor defina alguma heurística para escolher entre as duas abordagens com base no número de versões de pacote ou no tamanho cumulativo de folhas de pacote.

Armazenar todas as versões do pacote (folhas) no índice de registro gera economia no número de solicitações HTTP necessárias para buscar metadados do pacote, mas significa que um documento maior deve ser baixado e mais memória do cliente deve ser alocada. Por outro lado, se a implementação do servidor armazena imediatamente folhas de registro em documentos de página separados, o cliente deve executar mais solicitações HTTP para obter as informações necessárias.

A heurística que o nuget.org usa é a seguinte: se houver 128 ou mais versões de um pacote, quebre as folhas em páginas de tamanho 64. Se houver menos de 128 versões, insira todas as folhas no índice de registro. Observe que isso significa que pacotes de 65 a 127 versões terão duas páginas no índice, mas ambas as páginas serão embutidas.

GET {@id}/{LOWER_ID}/index.json

Parâmetros da solicitação

O valor LOWER_ID é a ID do pacote desejado em minúsculas usando as regras implementadas pelo método System.String.ToLowerInvariant() da .NET.

Resposta

A resposta é um documento JSON que tem um objeto raiz com as seguintes propriedades:

Cada item na matriz items do objeto de índice é um objeto JSON que representa uma página de registro.

Objeto da página de registro

O objeto da página de registro encontrado no índice de registro tem as seguintes propriedades:

Os limites lower e upper do objeto de página são úteis quando os metadados para uma versão de página específica são necessários. Esses limites podem ser usados para buscar a única página de registro necessária. As cadeias de caracteres de versão seguem as regras de versão do NuGet. As cadeias de caracteres de versão são normalizadas e não incluem metadados de compilação. Como acontece com todas as versões no ecossistema do NuGet, a comparação de cadeias de caracteres da versão é implementada usando as regras de precedência de versão do SemVer 2.0.0.

A propriedade parent só aparecerá se o objeto de página de registro tiver a propriedade items.

Se a propriedade items não estiver presente no objeto de página de registro, a URL especificada em @id deve ser usada para buscar metadados sobre versões de pacotes individuais. Às vezes, a matriz items é excluída do objeto de página como uma otimização. Se o número de versões de uma única ID de pacote for muito grande, o documento de índice de registro será enorme e desperdiçado para processar para um cliente que só se preocupa com uma versão específica ou um pequeno intervalo de versões.

Observe que, se a propriedade items estiver presente, a propriedade @id não precisará ser usada, pois todos os dados da página já estão embutidos na propriedade items.

Cada item na matriz items do objeto de página é um objeto JSON que representa uma folha de registro e seus metadados associados.

Objeto folha de registro em uma página

O objeto folha de registro encontrado em uma página de registro tem as seguintes propriedades:

Cada objeto folha de registro representa dados associados a uma única versão do pacote.

Entrada do catálogo

A propriedade catalogEntry no objeto folha de registro tem as seguintes propriedades:

A propriedade version do pacote é a cadeia de caracteres de versão completa após a normalização. Isso significa que os dados de compilação do SemVer 2.0.0 podem ser incluídos aqui.

A propriedade dependencyGroups é uma matriz de objetos que representa as dependências do pacote, agrupadas por estrutura de destino. Se o pacote não tiver dependências, a propriedade dependencyGroups está ausente, uma matriz vazia ou a propriedade dependencies de todos os grupos está vazia ou ausente.

O valor da propriedade licenseExpression está em conformidade com a sintaxe da expressão de licença do NuGet.

Grupo de dependência de pacote

Cada objeto de grupo de dependência tem as seguintes propriedades:

A cadeia de caracteres targetFramework usa o formato implementado pela biblioteca do .NET NuGet.Frameworks do NuGet. Se nenhum targetFramework for especificado, o grupo de dependência se aplicará a todas as estruturas de destino.

A propriedade dependencies é uma matriz de objetos, cada um representando uma dependência de pacote do pacote atual.

Dependência de pacote

Cada dependência de pacote tem as seguintes propriedades:

Se a propriedade range for excluída ou uma cadeia de caracteres vazia, o cliente deverá usar como padrão o intervalo de versão (, ). Ou seja, qualquer versão da dependência é permitida. O valor de * não é permitido para a propriedade range.

Reprovação de pacote

Cada depreciação de pacote tem as seguintes propriedades:

A propriedade reasons deve conter pelo menos uma cadeia de caracteres e deve conter apenas cadeias de caracteres da tabela a seguir:

Se a propriedade reasons contiver cadeias de caracteres que não são do conjunto conhecido, elas deverão ser ignoradas. As cadeias de caracteres não diferenciam maiúsculas de minúsculas, portanto legacy devem ser tratado da mesma forma que Legacy. Não há restrição de ordenação na matriz, portanto, as cadeias de caracteres podem ser organizadas em qualquer ordem arbitrária. Além disso, se a propriedade contiver apenas cadeias de caracteres que não são do conjunto conhecido, ela deverá ser tratada como se contivesse apenas a cadeia de caracteres “Outra”.

Pacote alternativo

O objeto do pacote alternativo tem as seguintes propriedades:

Vulnerabilidades

Uma matriz de objetos vulnerability. Cada vulnerabilidade tem as seguintes propriedades:

Solicitação de exemplo

GET https://api.nuget.org/v3/registration-sample/nuget.server.core/index.json

Efetue fetch do URL base (https://api.nuget.org/v3/registration-sample/ neste exemplo) do índice de serviço, conforme mencionado na seção URL base.

Resposta de exemplo

{
  "count": 1,
  "items": [
    {
      "@id": "https://api.nuget.org/v3/registration-sample/nuget.server.core/index.json#page/3.0.0-beta/3.0.0-beta",
      "count": 1,
      "items": [
        {
          "@id": "https://api.nuget.org/v3/registration-sample/nuget.server.core/3.0.0-beta.json",
          "catalogEntry": {
            "@id": "https://api.nuget.org/v3/catalog0/data/2017.10.05.18.41.33/nuget.server.core.3.0.0-beta.json",
            "authors": ".NET Foundation",
            "dependencyGroups": [
              {
                "@id": "https://api.nuget.org/v3/catalog0/data/2017.10.05.18.41.33/nuget.server.core.3.0.0-beta.json#dependencygroup",
                "dependencies": [
                  {
                    "@id": "https://api.nuget.org/v3/catalog0/data/2017.10.05.18.41.33/nuget.server.core.3.0.0-beta.json#dependencygroup/nuget.core",
                    "id": "NuGet.Core",
                    "range": "[2.14.0, )",
                    "registration": "https://api.nuget.org/v3/registration-sample/nuget.core/index.json"
                  }
                ]
              }
            ],
            "description": "Core library for creating a Web Application used to host a simple NuGet feed",
            "iconUrl": "",
            "id": "NuGet.Server.Core",
            "language": "",
            "licenseUrl": "https://raw.githubusercontent.com/NuGet/NuGet.Server/dev/LICENSE.txt",
            "listed": true,
            "minClientVersion": "2.6",
            "packageContent": "https://api.nuget.org/v3-flatcontainer/nuget.server.core/3.0.0-beta/nuget.server.core.3.0.0-beta.nupkg",
            "projectUrl": "https://github.com/NuGet/NuGet.Server",
            "published": "2017-10-05T18:40:32.43+00:00",
            "requireLicenseAcceptance": false,
            "summary": "",
            "tags": [ "" ],
            "title": "",
            "version": "3.0.0-beta",
            "vulnerabilities": [
              {
                "advisoryUrl": "https://github.com/advisories/ABCD-1234-5678-9012",
                "severity": "2"
              }
            ]
          },
          "packageContent": "https://api.nuget.org/v3-flatcontainer/nuget.server.core/3.0.0-beta/nuget.server.core.3.0.0-beta.nupkg",
          "registration": "https://api.nuget.org/v3/registration-sample/nuget.server.core/index.json"
        }
      ],
      "lower": "3.0.0-beta",
      "upper": "3.0.0-beta"
    }
  ]
}

Nesse caso específico, o índice de registro tem a página de registro embutida para que nenhuma solicitação extra seja necessária para buscar metadados sobre versões de pacotes individuais.

Página de registro

A página de registro contém folhas de registro. A URL para buscar uma página de registro é determinada pela propriedade @id no objeto da página de registro mencionado acima. A URL não deve ser previsível e sempre deve ser descoberta por meio do documento de índice.

Quando a matriz items não é fornecida no índice de registro, uma solicitação HTTP GET do valor @id retornará um documento JSON que tem um objeto como raiz. O objeto tem as seguintes propriedades:

A forma dos objetos da folha de registro é a mesma do índice de registro acima.

Solicitação de exemplo

GET https://api.nuget.org/v3/registration-sample/ravendb.client/page/1.0.531/1.0.729-unstable.json

Efetue fetch do URL base (https://api.nuget.org/v3/registration-sample/ neste exemplo) do índice de serviço, conforme mencionado na seção URL base.

Resposta de exemplo

{
  "count": 2,
  "lower": "1.0.531",
  "parent": "https://api.nuget.org/v3/registration-sample/nuget.protocol.v3.example/index.json",
  "upper": "1.0.729-unstable",
  "items": [
    {
      "@id": "https://api.nuget.org/v3/registration-sample/nuget.protocol.v3.example/1.0.531.json",
      "@type": "Package",
      "commitId": "e0b9ca79-75b5-414f-9e3e-de9534b5cfd1",
      "commitTimeStamp": "2017-10-26T14:12:19.3439088Z",
      "catalogEntry": {
        "@id": "https://api.nuget.org/v3/catalog0/data/2015.02.01.11.38.37/nuget.protocol.v3.example.1.0.531.json",
        "@type": "PackageDetails",
        "authors": "NuGet.org Team",
        "iconUrl": "https://www.nuget.org/Content/gallery/img/default-package-icon.svg",
        "id": "NuGet.Protocol.V3.Example",
        "licenseUrl": "http://www.opensource.org/licenses/ms-pl",
        "listed": false,
        "packageContent": "https://api.nuget.org/v3-flatcontainer/nuget.protocol.v3.example/1.0.531/nuget.protocol.v3.example.1.0.531.nupkg",
        "projectUrl": "https://github.com/NuGet/NuGetGallery",
        "published": "1900-01-01T00:00:00+00:00",
        "requireLicenseAcceptance": true,
        "title": "NuGet V3 Protocol Example",
        "version": "1.0.531"
      },
      "packageContent": "https://api.nuget.org/v3-flatcontainer/nuget.protocol.v3.example/1.0.531/nuget.protocol.v3.example.1.0.531.nupkg",
      "registration": "https://api.nuget.org/v3/registration-sample/nuget.protocol.v3.example/index.json"
    },
    {
      "@id": "https://api.nuget.org/v3/registration-sample/nuget.protocol.v3.example/1.0.729-unstable.json",
      "@type": "Package",
      "commitId": "e0b9ca79-75b5-414f-9e3e-de9534b5cfd1",
      "commitTimeStamp": "2017-10-26T14:12:19.3439088Z",
      "catalogEntry": {
        "@id": "https://api.nuget.org/v3/catalog0/data/2015.02.01.18.22.05/nuget.protocol.v3.example.1.0.729-unstable.json",
        "@type": "PackageDetails",
        "authors": "NuGet.org Team",
        "deprecation": {
          "reasons": [
            "CriticalBugs"
          ],
          "message": "This package is unstable and broken!",
          "alternatePackage": {
            "id": "Newtonsoft.JSON",
            "range": "12.0.2"
          }
        },
        "iconUrl": "https://www.nuget.org/Content/gallery/img/default-package-icon.svg",
        "id": "NuGet.Protocol.V3.Example",
        "licenseUrl": "http://www.opensource.org/licenses/ms-pl",
        "listed": false,
        "packageContent": "https://api.nuget.org/v3-flatcontainer/nuget.protocol.v3.example/1.0.729-unstable/nuget.protocol.v3.example.1.0.729-unstable.nupkg",
        "projectUrl": "https://github.com/NuGet/NuGetGallery",
        "published": "1900-01-01T00:00:00+00:00",
        "requireLicenseAcceptance": true,
        "summary": "This package is an example for the V3 protocol.",
        "title": "NuGet V3 Protocol Example",
        "version": "1.0.729-Unstable"
      },
      "packageContent": "https://api.nuget.org/v3-flatcontainer/nuget.protocol.v3.example/1.0.729-unstable/nuget.protocol.v3.example.1.0.729-unstable.nupkg",
      "registration": "https://api.nuget.org/v3/registration-sample/nuget.protocol.v3.example/index.json"
    }
  ]
}

Folha de registro

A folha de registro contém informações sobre uma ID e versão de pacote específicas. Os metadados sobre a versão específica podem não estar disponíveis neste documento. Os metadados do pacote devem ser obtidos no índice de registro ou na página de registro (que é descoberta usando o índice de registro).

A URL para buscar uma folha de registro é obtida da propriedade @id de um objeto de folha de registro em um índice de registro ou página de registro. Tal como acontece com o documento de página. a URL não deve ser previsível e deve sempre ser descoberta por meio do objeto da página de registro.

A folha de registro é um documento JSON com um objeto raiz com as seguintes propriedades:

Solicitação de exemplo

GET https://api.nuget.org/v3/registration-sample/nuget.versioning/4.3.0.json

Efetue fetch do URL base (https://api.nuget.org/v3/registration-sample/ neste exemplo) do índice de serviço, conforme mencionado na seção URL base.

Resposta de exemplo

{
  "@id": "https://api.nuget.org/v3/registration-sample/nuget.versioning/4.3.0.json",
  "catalogEntry": "https://api.nuget.org/v3/catalog0/data/2017.08.11.18.24.22/nuget.versioning.4.3.0.json",
  "listed": true,
  "packageContent": "https://api.nuget.org/v3-flatcontainer/nuget.versioning/4.3.0/nuget.versioning.4.3.0.nupkg",
  "published": "2017-08-11T18:24:14.36+00:00",
  "registration": "https://api.nuget.org/v3/registration-sample/nuget.versioning/index.json"
}