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.