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.exe e na CLI do .NET para executar operações do NuGet, como dotnet restore, pesquisar na interface do usuário do Visual Studio e nuget.exe push.
Observação: em alguns casos, nuget.org tem requisitos adicionais que não são impostos por outras origens de pacote. Essas diferenças são documentadas pelos protocolos do nuget.org.
Para obter uma enumeração simples e download das versões disponíveis do nuget.exe, consulte o ponto de extremidade tools.json .
Se você estiver implementando um repositório de pacotes do NuGet, consulte também o guia de implementação para obter requisitos e recomendações adicionais.
Índice de serviço
O ponto de entrada para a API é um documento JSON em um local bem conhecido. Esse 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 diferentes funcionalidades e atendem a diferentes casos de uso.
Os clientes que oferecem suporte à API devem aceitar uma ou mais dessas URLs de índice de serviço como meio de conexão com as respectivas origens de pacote.
Para obter mais informações sobre o índice de serviço, consulte a referência de API.
Controle de versão
A API é a versão 3 do protocolo HTTP do NuGet. Esse protocolo às vezes é chamado de “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 do índice de serviço é indicada pela propriedade version no índice de serviço. A API exige que a cadeia de caracteres da versão tenha um número de versão principal de 3. À medida que alterações sem interrupção são feitas no esquema de índice de serviço, a versão secundária da cadeia de caracteres da versão será aumentada.
Clientes mais antigos (como nuget.exe 2.x) não oferecem suporte à API V3 e têm suporte apenas para a 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 do NuGet oficial. A API V3 foi suportada pela primeira vez pela versão 3.0 do cliente do NuGet oficial e ainda é a versão de protocolo principal mais recente suportada pelo cliente do NuGet, 4.0 e posterior.
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 suportados é o seguinte:
| Nome do recurso | Necessária | Descrição |
|---|---|---|
| Catalog | não | Registro completo de todos os eventos do pacote. |
| PackageBaseAddress | sim | Obtenha o conteúdo do pacote (.nupkg). |
| PackageDetailsUriTemplate | não | Crie uma URL para acessar uma página da Web de detalhes do pacote. |
| PackagePublish | sim | Enviar e excluir pacotes (ou remover da lista). |
| RegistrationsBaseUrl | sim | Obter metadados de pacote. |
| ReportAbuseUriTemplate | não | Crie uma URL para acessar uma página da Web para relatar abuso. |
| RepositorySignatures | não | Obtenha certificados usados para assinatura de repositório. |
| SearchAutocompleteService | não | Descubra IDs de pacote e versões por substring. |
| SearchQueryService | sim | Filtre e pesquise pacotes por palavra-chave. |
| SymbolPackagePublish | não | Enviar pacotes de símbolos por push. |
| VulnerabilityInfo | não | Pacotes com vulnerabilidades conhecidas. |
Em geral, todos os dados não-binários retornados por um recurso da 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 entender devem ser ignoradas.
Observação
Quando uma fonte não implementa SearchAutocompleteService, nenhum comportamento de preenchimento automático deve ser desabilitado normalmente. Quando ReportAbuseUriTemplate não é implementado, o cliente oficial do NuGet retorna à URL para relatar abuso do nuget.org (rastreada por NuGet/Home#4924). Outros clientes podem optar por simplesmente não mostrar uma URL para relatar abuso ao usuário.
Recursos não documentados sobre o 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 se enquadra nessa categoria. O NuGetGallery usa esse recurso para delegar algumas consultas V2 (OData) ao nosso índice de pesquisa em vez de usar o banco de dados. Esse recurso foi introduzido por motivos 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 nessa categoria.
Em terceiro lugar, não documentamos recursos que estão fortemente acoplados ao protocolo V2, que, em si, não é 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. Este recurso suporta o nuget.exe list.
Se um recurso não estiver documentado aqui, é altamente recomendável que você não tenha uma dependência dele. Podemos remover ou alterar o comportamento desses recursos não documentados que podem interromper sua implementação de maneiras inesperadas.
Carimbos de data/hora
Todos os carimbos de data/hora retornados pela API estão em UTC ou são especificados usando a representação ISO 8601 .
Métodos HTTP
| Verbo | Usar |
|---|---|
| GET | Executa uma operação somente leitura, normalmente recuperando dados. |
| HEAD | Busca os cabeçalhos de resposta para a solicitação GET correspondente. |
| PUT | Cria um recurso que não existe ou, se existir, atualiza-o. Alguns recursos podem não oferecer suporte à atualização. |
| DELETE | Exclui ou remove um recurso da lista. |
Códigos de status HTTP
| Código | Descrição |
|---|---|
| 200 | Êxito, e há um corpo da 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 | Êxito, mas não há corpo da resposta. |
| 301 | Um redirecionamento permanente. |
| 302 | 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 dadas as credenciais fornecidas. |
| 404 | O recurso solicitado não existe. |
| 409 | A solicitação está 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 arquivo GET na sequência. A documentação relativa a pontos de extremidade específicos não indicará explicitamente quando 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 do 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 enviar por push e excluir, consulte recurso PackagePublish |
| 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 protocolos do nuget.org |
| X-NuGet-Session-Id | Opcional. Os clientes do NuGet v4.7 ou superior identificam solicitações HTTP que fazem parte da mesma sessão de cliente do 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 packages.config restauração, 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 de origem do pacote definir. Por nuget.org, somente o recurso PackagePublish requer autenticação por meio de um cabeçalho de chave de API especial. Consulte recurso PackagePublish para obter detalhes.