API del servidor NuGet
La API del servidor NuGet es un conjunto de puntos de conexión HTTP que se pueden usar para descargar paquetes, capturar metadatos, publicar nuevos paquetes y realizar la mayoría de las demás operaciones disponibles en los clientes oficiales de NuGet.
El cliente de NuGet usa esta API en Visual Studio, nuget.exey la CLI de .NET para realizar operaciones de NuGet, como dotnet restore, buscar en la interfaz de usuario de Visual Studio y nuget.exe push.
Tenga en cuenta, en algunos casos, nuget.org tiene requisitos adicionales que no son aplicados por otros orígenes de paquetes. Estas diferencias se documentan mediante los protocolos de nuget.org.
Para obtener una enumeración sencilla y descarga de las versiones de nuget.exe disponibles, consulte el punto de conexión de tools.json.
Si va a implementar un repositorio de paquetes NuGet, consulte también la guía de implementación para obtener más 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 denomina í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 diferentes funcionalidades y cumplen diferentes casos de uso.
Los clientes que admiten la API deben aceptar una o varias 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, consulte su referencia de API.
Control de versiones
La API es la versión 3 del protocolo HTTP de NuGet. Este protocolo se conoce a veces como "API V3". Estos documentos de referencia harán referencia a esta versión del protocolo simplemente como "la API".
La versión del esquema del í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 realizan cambios no importantes en el esquema de índice de servicio, se aumentará 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 y solo admiten 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 versión más reciente del protocolo principal compatible con el cliente de NuGet, 4.0 y en.
Los cambios de protocolo no importantes se han realizado en la API desde que se publicó por primera vez.
Recursos y esquema
El índice de servicio describe una variedad de recursos. El conjunto actual de recursos admitidos es el siguiente:
| Nombre del recurso | Obligatorio | Descripción |
|---|---|---|
| catálogo de | No | Registro completo de todos los eventos de paquete. |
| PackageBaseAddress | Sí | Obtiene el contenido del paquete (.nupkg). |
| packageDetailsUriTemplate de | No | Construya una dirección URL para acceder a una página web de detalles del paquete. |
| PackagePublish | Sí | Insertar y eliminar (o anular la lista) de paquetes. |
| ReadmeUriTemplate | No | Construya una dirección URL para acceder al ARCHIVO LÉAME de un paquete. |
| RegistrationsBaseUrl | Sí | Obtiene los metadatos del paquete. |
| ReportAbuseUriTemplate | No | Construya una dirección URL para acceder a una página web de abuso de informe. |
| RepositorySignatures | No | Obtenga certificados usados para la firma del repositorio. |
| SearchAutocompleteService | No | Descubra los identificadores de paquete y las versiones mediante la subcadena. |
| SearchQueryService | Sí | Filtre y busque paquetes por palabra clave. |
| SymbolPackagePublish | No | Insertar paquetes de símbolos. |
| 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, consulte los temas enumerados anteriormente.
En el futuro, a medida que evoluciona el protocolo, se pueden agregar nuevas propiedades a las respuestas JSON. Para que el cliente sea a prueba de futuro, la implementación no debe suponer que el esquema de respuesta es final y no puede incluir datos adicionales. Todas las propiedades que la implementación no entiende deben omitirse.
Nota
Cuando un origen no implementa SearchAutocompleteService ningún comportamiento de autocompletar debe deshabilitarse correctamente. Cuando no se implementa ReportAbuseUriTemplate, el cliente de NuGet oficial vuelve a la dirección URL de abuso del informe de nuget.org (rastreada por NuGet/Home#4924). Otros clientes pueden optar por no mostrar simplemente una dirección URL de abuso de informe al usuario.
Recursos no documentados en nuget.org
El índice de servicio V3 de nuget.org tiene algunos recursos que no están documentados anteriormente. Hay algunas razones para no documentar un recurso.
En primer lugar, no documentamos los recursos usados como detalle de implementación de nuget.org. El SearchGalleryQueryService se encuentra en esta categoría.
NuGetGallery usa este recurso para delegar algunas consultas V2 (OData) en nuestro índice de búsqueda en lugar de usar 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 está documentado intencionadamente. El recurso LegacyGallery se encuentra en esta categoría. Este recurso permite que un índice de servicio V3 apunte a una dirección URL de origen V2 correspondiente. Este recurso admite el nuget.exe list.
Si no se documenta un recurso aquí, se recomienda encarecidamente que no dependa de ellos. Podemos quitar 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 iso 8601 representación.
Métodos HTTP
| Verbo | Uso |
|---|---|
| OBTENER | Realiza una operación de solo lectura, normalmente recuperando datos. |
| CABEZA | Captura los encabezados de respuesta de la solicitud de GET correspondiente. |
| PONER | Crea un recurso que no existe o, si existe, lo actualiza. Es posible que algunos recursos no admitan la actualización. |
| BORRAR | Elimina o anula la lista de un recurso. |
Códigos de estado HTTP
| Código | Descripción |
|---|---|
| 200 | El éxito y hay un cuerpo de respuesta. |
| 201 | Correcto y se creó el recurso. |
| 202 | Correcto, se ha aceptado la solicitud, pero es posible que algunos trabajos sigan siendo incompletos y completados de forma asincrónica. |
| 204 | Correcto, pero no hay ningún cuerpo de respuesta. |
| 301 | Una redirección permanente. |
| 302 | Redirección 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 encontrado un error inesperado. |
| 503 | El servicio no está disponible temporalmente. |
Cualquier GET solicitud realizada a un punto de conexión de API puede devolver una redirección HTTP (301 o 302). Los clientes deben controlar correctamente estos redireccionamientos observando el encabezado Location y emitiendo un GETposterior. La documentación relativa a puntos de conexión específicos no indicará explícitamente dónde se pueden usar 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, consulte de recursos dePackagePublish |
| X-NuGet:Client-Version |
en desuso y reemplazados por X-NuGet-Protocol-Version |
| X-NuGet:Protocol-Version | Requerido en determinados casos solo en nuget.org, consulte nuget.org protocolos |
| 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 sola restauración en PackageReference. En otros escenarios, como autocompletar y packages.config restauración, puede haber varios identificadores de sesión diferentes debido a cómo se factoriza el código.
Autenticación
La autenticación se deja hasta la implementación del origen del paquete que se va a definir. Para nuget.org, solo el recurso de PackagePublish requiere autenticación a través de un encabezado de clave de API especial. Consulte PackagePublish de recursos para obtener más información.