API do Servidor NuGet
A API do NuGet Server é 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. Estas diferenças estão documentadas pelos Protocolosnuget.org .
Para uma enumeração simples e download das versões nuget.exe disponíveis, consulte o ponto de extremidade tools.json.
Se você estiver implementando um repositório de pacotes NuGet, consulte também do guia de implementação para obter requisitos e recomendações adicionais.
Índice de serviços
O ponto de entrada para a API é um documento JSON em um local bem conhecido. Este documento é chamado de índice de serviço . A localização 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 diferentes funcionalidades e atendem a diferentes casos de uso.
Os clientes que suportam a API devem aceitar uma ou mais dessas URLs de índice de serviço como meio de conexão com as respetivas fontes de pacote.
Para obter mais informações sobre o índice de serviço, consulte seude referência de API .
Controle de versão
A API é a versão 3 do protocolo HTTP do NuGet. Este protocolo é por vezes referido como "a API V3". Esses documentos de referência se referirão a esta 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 exige que a cadeia de caracteres de versão tenha um número de versão principal de 3. À medida que forem feitas alterações ininterruptas 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 o nuget.exe 2.x) não suportam a API V3 e suportam apenas a API V2 mais antiga, que não está documentada aqui.
A API NuGet V3 é nomeada como tal porque é a sucessora da API V2, que era o protocolo baseado em OData implementado pela versão 2.x do cliente NuGet oficial. A API V3 foi suportada pela primeira vez pela versão 3.0 do cliente NuGet oficial e ainda é a última versão de protocolo principal suportada pelo cliente NuGet, 4.0 e seguintes.
Alterações de protocolo ininterruptas 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 suportados é o seguinte:
| Nome do recurso | Necessário | Descrição |
|---|---|---|
| Catálogo | Não | Registo completo de todos os eventos do pacote. |
| PackageBaseAddress | Sim | Obtenha o conteúdo do pacote (.nupkg). |
| PackageDetailsUriTemplate | Não | Construa uma URL para acessar uma página da Web de detalhes do pacote. |
| PackagePublish | Sim | Empurre e exclua (ou cancele a lista) de pacotes. |
| ReadmeUriTemplate | Não | Construa uma URL para acessar o LEIA-ME de um pacote. |
| RegistrationsBaseUrl | Sim | Obtenha metadados do pacote. |
| ReportAbuseUriTemplate | Não | Construa uma URL para acessar uma página da Web de denúncia de abuso. |
| RepositorySignatures | Não | Obtenha certificados usados para assinatura de repositório. |
| SearchAutocompleteService | Não | Descubra IDs e versões de pacotes por substring. |
| SearchQueryService | Sim | Filtre e pesquise pacotes por palavra-chave. |
| SymbolPackagePublish | Não | Empurre pacotes de símbolos. |
| 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 esteja preparado para o 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.
Observação
Quando uma fonte não implementa SearchAutocompleteService qualquer comportamento de preenchimento automático deve ser desativado normalmente. Quando ReportAbuseUriTemplate não é implementado, o cliente NuGet oficial recorre ao URL de denúncia de abuso do nuget.org (rastreado por NuGet/Home#4924). Outros clientes podem optar por simplesmente não mostrar uma URL de denúncia de abuso ao usuário.
Recursos não documentados no nuget.org
O índice de serviço V3 no nuget.org tem alguns recursos que não estão documentados acima. Existem algumas razões para não documentar um recurso.
Primeiro, não documentamos os recursos usados como um detalhe de implementação do nuget.org. O SearchGalleryQueryService enquadra-se nesta categoria.
NuGetGallery usa esse recurso para delegar algumas consultas V2 (OData) ao nosso índice de pesquisa em vez de usar o banco de dados. Este recurso foi introduzido por razões de escalabilidade e não se destina a 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 nesta categoria.
Em terceiro lugar, não documentamos recursos que estão intimamente ligados ao protocolo V2, que é intencionalmente não documentado. O recurso LegacyGallery enquadra-se nesta categoria. Este recurso permite que um índice de serviço V3 aponte para uma URL de origem V2 correspondente. Este recurso suporta o nuget.exe list.
Se um recurso não estiver documentado aqui, recomendamos vivamente que não dependa dele. Podemos remover ou alterar o comportamento desses recursos não documentados, o que pode interromper sua implementação de maneiras inesperadas.
Carimbos de data/hora
Todos os carimbos de data/hora retornados pela API são UTC ou são especificados de outra forma usando representação de ISO 8601.
Métodos HTTP
| Verbo | Utilização |
|---|---|
| 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. |
| COLOCAR | Cria um recurso que não existe ou, se existir, atualiza-o. Alguns recursos podem não suportar a atualização. |
| SUPRIMIR | Exclui ou cancela a lista de um recurso. |
Códigos de status HTTP
| Código | Descrição |
|---|---|
| 200 | Sucesso, e há um corpo de resposta. |
| 201 | Sucesso, e o recurso foi criado. |
| 202 | Sucesso, 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 no 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 dadas 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 da API pode retornar um redirecionamento HTTP (301 ou 302). Os clientes devem lidar graciosamente com esses redirecionamentos, observando o cabeçalho Location e emitindo um GETsubsequente. A documentação relativa a pontos finais específicos não indicará explicitamente onde os redirecionamentos podem ser usados.
No caso de um código de status de nível 500, 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 nível 500 ou erro TCP/DNS.
Cabeçalhos de solicitação HTTP
| Designação | Descrição |
|---|---|
| X-NuGet-ApiKey | Necessário para enviar por push e excluir, consulte PackagePublish de recursos |
| X-NuGet-Client-Version |
preterido e substituído por X-NuGet-Protocol-Version |
| X-NuGet-Protocol-Version | Obrigatório em certos casos apenas 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 no PackageReference. Para outros cenários, como preenchimento automático e restauração packages.config, pode haver vários IDs de sessão diferentes devido à forma como o código é fatorado.
Autenticação
A autenticação é deixada para a implementação de origem do pacote para definir. Por nuget.org, apenas o recurso PackagePublish requer autenticação por meio de um cabeçalho de chave de API especial. Consulte PackagePublish de recursos para obter detalhes.