API do Servidor NuGet
A API do Servidor NuGet é um conjunto de pontos de extremidade HTTP que podem ser usados para baixar pacotes, buscar metadados, publicar novos pacotes e executar a maioria das outras operações disponíveis nos clientes oficiais do NuGet.
Essa API é usada pelo cliente NuGet no Visual Studio, nuget.exee pela CLI do .NET para executar operações do NuGet, como dotnet restore, pesquisa na interface do usuário do Visual Studio e nuget.exe push.
Observe que, em alguns casos, nuget.org tem requisitos adicionais que não são impostos por outras fontes de pacote. Essas diferenças são documentadas pelo protocolosnuget.org .
Para obter uma enumeração simples e baixar as versões de nuget.exe disponíveis, consulte o ponto de extremidade tools.json.
Se você estiver implementando um repositório de pacotes NuGet, consulte também o guia de implementação para obter requisitos e recomendações adicionais.
Índice de serviço
O ponto de entrada da API é um documento JSON em um local conhecido. Este documento é chamado de índice de serviço . O local do índice de serviço para nuget.org é https://api.nuget.org/v3/index.json.
Este documento JSON contém uma lista de recursos que fornecem funcionalidades diferentes e atendem a diferentes casos de uso.
Os clientes que dão suporte à API devem aceitar uma ou mais dessas URLs de índice de serviço como o meio de se conectar às respectivas fontes de pacote.
Para obter mais informações sobre o índice de serviço, consulte sua referência de API.
Controle de versão
A API é a versão 3 do protocolo HTTP do NuGet. Às vezes, esse protocolo é chamado de "API V3". Esses documentos de referência se referirão a essa versão do protocolo simplesmente como "a API".
A versão do esquema de índice de serviço é indicada pela propriedade version no índice de serviço. A API determina que a cadeia de caracteres de versão tenha um número de versão principal de 3. À medida que alterações não significativas são feitas no esquema de índice de serviço, a versão secundária da cadeia de caracteres de versão será aumentada.
Clientes mais antigos (como nuget.exe 2.x) não dão suporte à API V3 e só dão suporte à API V2 mais antiga, que não está documentada aqui.
A API do NuGet V3 é nomeada como tal porque é a sucessora da API V2, que foi o protocolo baseado em OData implementado pela versão 2.x do cliente NuGet oficial. A API V3 foi compatível pela primeira vez com a versão 3.0 do cliente Oficial do NuGet e ainda é a versão de protocolo principal mais recente compatível com o cliente NuGet, 4.0 e assim por diante.
Alterações de protocolo sem interrupção foram feitas na API desde que ela foi lançada pela primeira vez.
Recursos e esquema
O índice de serviço descreve uma variedade de recursos. O conjunto atual de recursos com suporte é o seguinte:
| Nome do recurso | Necessário | Descrição |
|---|---|---|
| do Catálogo | Não | Registro completo de todos os eventos do pacote. |
| PackageBaseAddress | Sim | Obter conteúdo do pacote (.nupkg). |
| PackageDetailsUriTemplate | Não | Construa uma URL para acessar uma página da Web de detalhes do pacote. |
| PackagePublish | Sim | Enviar por push e excluir (ou não listar) pacotes. |
| ReadmeUriTemplate | Não | Construa uma URL para acessar o README de um pacote. |
| RegistrationsBaseUrl | Sim | Obter metadados do pacote. |
| ReportAbuseUriTemplate | Não | Construa uma URL para acessar uma página da Web de abuso de relatório. |
| repositórioSignatures | Não | Obter certificados usados para assinatura de repositório. |
| SearchAutocompleteService | Não | Descubra IDs e versões do pacote usando subcadeia de caracteres. |
| SearchQueryService | Sim | Filtrar e pesquisar pacotes por palavra-chave. |
| SymbolPackagePublish | Não | Enviar pacotes de símbolo por push. |
| VulnerabilityInfo | Não | Pacotes com vulnerabilidades conhecidas. |
Em geral, todos os dados não binários retornados por um recurso de API são serializados usando JSON. O esquema de resposta retornado por cada recurso no índice de serviço é definido individualmente para esse recurso. Para obter mais informações sobre cada recurso, consulte os tópicos listados acima.
No futuro, à medida que o protocolo evolui, novas propriedades podem ser adicionadas às respostas JSON. Para que o cliente seja à prova de futuro, a implementação não deve assumir que o esquema de resposta é final e não pode incluir dados extras. Todas as propriedades que a implementação não entende devem ser ignoradas.
Nota
Quando uma origem não implementa SearchAutocompleteService qualquer comportamento de preenchimento automático deve ser desabilitado normalmente. Quando ReportAbuseUriTemplate não for implementado, o cliente oficial do NuGet retornará à URL de abuso de relatório do nuget.org (controlada por NuGet/Home#4924). Outros clientes podem optar por simplesmente não mostrar uma URL de abuso de relatório para o usuário.
Recursos não documentados em nuget.org
O índice de serviço V3 no nuget.org tem alguns recursos que não estão documentados acima. Há alguns motivos para não documentar um recurso.
Primeiro, não documentamos os recursos usados como um detalhe de implementação de nuget.org. O SearchGalleryQueryService se enquadra nessa categoria.
NuGetGallery usa esse recurso para delegar algumas consultas V2 (OData) ao índice de pesquisa em vez de usar o banco de dados. Esse recurso foi introduzido por motivos de escalabilidade e não se destina ao uso externo.
Em segundo lugar, não documentamos recursos que nunca foram enviados em uma versão RTM do cliente oficial.
PackageDisplayMetadataUriTemplate e PackageVersionDisplayMetadataUriTemplate se enquadram nessa categoria.
Em terceiro lugar, não documentamos recursos que estão firmemente acoplados ao protocolo V2, que por si só não está documentado intencionalmente. O recurso LegacyGallery se enquadra nessa categoria. Esse recurso permite que um índice de serviço V3 aponte para uma URL de origem V2 correspondente. Esse recurso dá suporte ao nuget.exe list.
Se um recurso não estiver documentado aqui, altamente recomendamos que você não tenha uma dependência neles. Podemos remover ou alterar o comportamento desses recursos não documentados que podem interromper sua implementação de maneiras inesperadas.
Timestamps
Todos os carimbos de data/hora retornados pela API são UTC ou são especificados usando representação de ISO 8601.
Métodos HTTP
| Verbo | Usar |
|---|---|
| OBTER | Executa uma operação somente leitura, normalmente recuperando dados. |
| CABEÇA | Busca os cabeçalhos de resposta para a solicitação de GET correspondente. |
| PÔR | Cria um recurso que não existe ou, se ele existir, o atualiza. Alguns recursos podem não dar suporte à atualização. |
| EXCLUIR | Exclui ou deslista um recurso. |
Códigos de status HTTP
| Código | Descrição |
|---|---|
| 200 | Sucesso, e há um corpo de resposta. |
| 201 | Êxito e o recurso foi criado. |
| 202 | Êxito, a solicitação foi aceita, mas alguns trabalhos ainda podem estar incompletos e concluídos de forma assíncrona. |
| 204 | Sucesso, mas não há corpo de resposta. |
| 301 | Um redirecionamento permanente. |
| 302 | Um redirecionamento temporário. |
| 400 | Os parâmetros na URL ou no corpo da solicitação não são válidos. |
| 401 | As credenciais fornecidas são inválidas. |
| 403 | A ação não é permitida considerando as credenciais fornecidas. |
| 404 | O recurso solicitado não existe. |
| 409 | A solicitação entra em conflito com um recurso existente. |
| 500 | O serviço encontrou um erro inesperado. |
| 503 | O serviço está temporariamente indisponível. |
Qualquer solicitação GET feita a um ponto de extremidade de API pode retornar um redirecionamento HTTP (301 ou 302). Os clientes devem lidar normalmente com esses redirecionamentos observando o cabeçalho Location e emitindo um GETsubsequente. A documentação sobre pontos de extremidade específicos não chamará explicitamente onde os redirecionamentos podem ser usados.
No caso de um código de status de 500 níveis, o cliente pode implementar um mecanismo de repetição razoável. O cliente NuGet oficial tenta novamente três vezes ao encontrar qualquer código de status de 500 níveis ou erro TCP/DNS.
Cabeçalhos de solicitação HTTP
| Nome | Descrição |
|---|---|
| X-NuGet-ApiKey | Necessário para push e exclusão, consulte PackagePublish de recursos |
| X-NuGet-Client-Version |
preterido e substituído por X-NuGet-Protocol-Version |
| X-NuGet-Protocol-Version | Necessário em determinados casos somente em nuget.org, consulte nuget.org protocolos |
| X-NuGet-Session-Id | opcional. Os clientes NuGet v4.7+ identificam solicitações HTTP que fazem parte da mesma sessão do cliente NuGet. |
O X-NuGet-Session-Id tem um único valor para todas as operações relacionadas a uma única restauração em PackageReference. Para outros cenários, como preenchimento automático e restauração packages.config pode haver várias IDs de sessão diferentes devido à forma como o código é fatorado.
Autenticação
A autenticação é deixada para a implementação da origem do pacote a ser definida. Para nuget.org, somente o recurso PackagePublish requer autenticação por meio de um cabeçalho de chave de API especial. Consulte PackagePublish de recursos para obter detalhes.