API del servidor de NuGet

La API del servidor NuGet es un conjunto de puntos de conexión HTTP que se pueden utilizar para descargar paquetes, capturar metadatos, publicar nuevos paquetes y realizar casi todas las operaciones disponibles en los clientes oficiales de NuGet.

El cliente NuGet utiliza esta API en Visual Studio, nuget.exe y la CLI de .NET para realizar operaciones de NuGet como dotnet restore, búsquedas en la UI de Visual Studio y nuget.exe push.

Nota: En algunos casos, nuget.org tiene requisitos adicionales que no aplican otros orígenes de paquetes. Estas diferencias se documentan mediante los protocolos de nuget.org.

Para obtener una enumeración simple y la descarga de las versiones disponibles de nuget.exe, consulta el punto de conexión tools.json.

Si vas a implementar un repositorio de paquetes de NuGet, consulta también la guía de implementación para conocer otros requisitos y recomendaciones.

Índice de servicio

El punto de entrada de la API es un documento JSON en una ubicación conocida. Este documento se llama índice de servicio. La ubicación del índice de servicio para nuget.org es https://api.nuget.org/v3/index.json.

Este documento JSON contiene una lista de recursos que proporcionan una funcionalidad diferente y cumplen distintos casos de uso.

Los clientes que admiten la API deben aceptar una o más de estas direcciones URL de índice de servicio como medio para conectarse a los orígenes de paquete respectivos.

Para obtener más información sobre el índice de servicio, consulta su referencia en la API.

Control de versiones

La API es la versión 3 del protocolo HTTP de NuGet. El protocolo se conoce a veces como “API V3”. Estos documentos de referencia se referirán a esta versión del protocolo simplemente como “la API”.

La versión del esquema de índice de servicio se indica mediante la propiedad version en el índice de servicio. La API exige que la cadena de versión tenga un número de versión principal de 3. A medida que se realicen cambios no importantes en el esquema del índice de servicio, se incrementará la versión secundaria de la cadena de versión.

Los clientes más antiguos (como nuget.exe 2.x) no admiten la API V3, solo la API V2 anterior, que no está documentada aquí.

La API de NuGet V3 se denomina como tal porque es la sucesora de la API V2, que era el protocolo basado en OData implementado por la versión 2.x del cliente NuGet oficial. La API V3 fue compatible por primera vez con la versión 3.0 del cliente NuGet oficial y sigue siendo la última versión del protocolo principal compatible con el cliente de NuGet de la versión 4.0 y superiores.

Desde que la API se publicó por primera vez, se le han realizado algunos cambios leves de protocolo.

Esquema y recursos

El índice de servicio describe una variedad de recursos. El conjunto actual de recursos admitidos es el siguiente:

Nombre del recurso	Requerido	Descripción
Catalog	no	Registro completo de todos los eventos de paquete.
PackageBaseAddress	sí	Obtención del contenido del paquete (.nupkg).
PackageDetailsUriTemplate	no	Construcción de una dirección URL para acceder a la página web de detalles de un paquete.
PackagePublish	sí	Inserción y eliminación (o anulación de la lista) de paquetes.
RegistrationsBaseUrl	sí	Obtención de metadatos de paquete.
ReportAbuseUriTemplate	no	Construcción de una dirección URL para acceder a una página web Notificar abuso.
RepositorySignatures	no	Obtención de certificados utilizados para la firma del repositorio.
SearchAutocompleteService	no	Descubrimiento de versiones e id. de paquete mediante la substring.
SearchQueryService	sí	Filtrado y búsqueda de paquetes por palabra clave.
SymbolPackagePublish	no	Paquetes de símbolos de inserción.
VulnerabilityInfo	no	Paquetes con vulnerabilidades conocidas.

En general, todos los datos no binarios devueltos por un recurso de API se serializan mediante JSON. El esquema de respuesta devuelto por cada recurso del índice de servicio se define individualmente para ese recurso. Para obtener más información sobre cada recurso, consulta los temas enumerados anteriormente.

Posteriormente, a medida que evoluciona el protocolo, se pueden agregar nuevas propiedades a las respuestas JSON. Para garantizar la eficacia futura del cliente, la implementación no debe suponer que el esquema de respuesta es final y no puede incluir datos adicionales. Debes ignorar todas las propiedades que la implementación no reconozca.

Nota:

Cuando un origen no implementa SearchAutocompleteService, cualquier comportamiento de autocompletar debe deshabilitarse correctamente. Si no se implementa ReportAbuseUriTemplate, el cliente de NuGet oficial vuelve a la dirección URL Notificar abuso de nuget.org (de la cual hace un seguimiento NuGet/Home#4924). Otros clientes pueden optar por no mostrar al usuario una dirección URL Notificar abuso.

Recursos no documentados en nuget.org

El índice de servicio V3 de nuget.org tiene algunos recursos que no están documentados arriba. Existen algunas razones para no documentar un recurso.

En primer lugar, no documentamos los recursos utilizados como detalle de implementación de nuget.org. SearchGalleryQueryService entra en esta categoría. NuGetGallery utiliza este recurso para delegar algunas consultas V2 (OData) en nuestro índice de búsqueda en lugar de utilizar la base de datos. Este recurso se introdujo por motivos de escalabilidad y no está pensado para uso externo.

En segundo lugar, no documentamos recursos que nunca se enviaron en una versión RTM del cliente oficial. PackageDisplayMetadataUriTemplate y PackageVersionDisplayMetadataUriTemplate entran en esta categoría.

En tercer lugar, no documentamos recursos que están estrechamente unidos al protocolo V2, que, a su vez, no se documenta intencionadamente. El recurso LegacyGallery entra en esta categoría. Este recurso permite al índice de servicio V3 apuntar a una dirección URL de origen V2 correspondiente. Este recurso admite la nuget.exe list.

Si un recurso no está documentado aquí, se recomienda encarecidamente no depender de él. Podemos eliminar o cambiar el comportamiento de estos recursos no documentados que podrían interrumpir la implementación de maneras inesperadas.

Marcas de tiempo

Todas las marcas de tiempo devueltas por la API son UTC o se especifican de otro modo mediante la manifestación ISO 8601.

Métodos HTTP

Verbo	Usar
OBTENER	Realiza una operación de solo lectura, normalmente recuperando datos.
HEAD	Captura los encabezados de respuesta de la solicitud GET correspondiente.
PUT	Crea un recurso que no existe o, si existe, lo actualiza. Es posible que algunos recursos no admitan la actualización.
Delete	Elimina o anula un recurso de una lista.

Códigos de estado HTTP

Código	Descripción
200	Correcto, y existe un cuerpo de la respuesta.
201	Correcto, y se ha creado el recurso.
202	Correcto, se ha aceptado la solicitud, pero es posible que algunos trabajos sigan estando incompletos y que se completen de forma asíncrona.
204	Correcto, pero no existe ningún cuerpo de la respuesta.
301	Redireccionamiento permanente.
302	Redireccionamiento temporal.
400	Los parámetros de la dirección URL o del cuerpo de la solicitud no son válidos.
401	Las credenciales proporcionadas no son válidas.
403	No se permite la acción dadas las credenciales proporcionadas.
404	El recurso solicitado no existe.
409	La solicitud entra en conflicto con un recurso existente.
500	El servicio ha detectado un error inesperado.
503	El servicio no está disponible temporalmente.

Cualquier solicitud GET realizada a un punto de conexión de API puede devolver un redireccionamiento HTTP (301 o 302). Los clientes deben manipular correctamente estos redireccionamientos observando el encabezado Location y emitiendo después un GET. La documentación relativa a puntos de conexión específicos no indicará explícitamente dónde se pueden utilizar los redireccionamientos.

En el caso de un código de estado de 500 niveles, el cliente puede implementar un mecanismo de reintento razonable. El cliente NuGet oficial vuelve a intentarlo tres veces al encontrar cualquier código de estado de 500 niveles o error TCP/DNS.

Encabezados de solicitud HTTP

Nombre	Descripción
X-NuGet-ApiKey	Obligatorio para la inserción y eliminación; consulta el recurso PackagePublish
X-NuGet-Client-Version	En desuso y reemplazado por X-NuGet-Protocol-Version
X-NuGet-Protocol-Version	Requerido en determinados casos solo en nuget.org; consulta los protocolos de nuget.org
X-NuGet-Session-Id	Opcional. Los clientes NuGet v4.7+ identifican las solicitudes HTTP que forman parte de la misma sesión de cliente de NuGet.

El X-NuGet-Session-Id tiene un valor único para todas las operaciones relacionadas con una única restauración en PackageReference. En otros escenarios, como autocompletar y la restauración de packages.config, puede haber varios id. de sesión diferentes debido a cómo se factoriza el código.

Autenticación

La autenticación viene definida por la implementación del origen del paquete. Para nuget.org, solo el PackagePublish recurso requiere autenticación a través de un encabezado de clave de API especial. Consulta el recurso PackagePublish para obtener más información.