API del servidor de NuGet
La API NuGet Server 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 de NuGet oficiales.
El cliente de NuGet usa esta API en Visual Studio, nuget.exe y la CLI de .NET para realizar operaciones de NuGet como , buscar en la interfaz de usuario de Visual Studio y dotnet restorenuget.exe push .
Tenga en cuenta que en algunos nuget.org tiene requisitos adicionales que otros orígenes de paquetes no aplican. Estas diferencias se documentan en nuget.org protocolos.
Para obtener una enumeración simple y descargar las versiones nuget.exe disponibles, consulte el punto de conexión tools.json.
Í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 funcionalidades diferentes y satisfacen distintos casos de uso.
Los clientes que admiten la API deben aceptar una o varias de estas direcciones URL de índice de servicio como medio de conectarse a los orígenes de paquete respectivos.
Para 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 NuGet protocolo HTTP de la aplicación. Este protocolo se conoce a veces como "LA 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 version la propiedad 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 y solo admiten la API V2 anterior, que no se documenta aquí.
La API 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 primero era compatible con la versión 3.0 del cliente oficial de NuGet y sigue siendo la versión más reciente del protocolo principal compatible con el cliente de NuGet, 4.0 y versiones 2.
Se han realizado cambios de protocolo no importantes 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 | Requerido | Descripción |
|---|---|---|
| Catálogo | no | Registro completo de todos los eventos de paquete. |
| PackageBaseAddress | Sí. | Obtiene el contenido del paquete (.nupkg). |
| PackageDetailsUriTemplate | no | Construya una dirección URL para acceder a una página web de detalles del paquete. |
| PackagePublish | sí | Inserción y eliminación (o eliminación de la lista) de paquetes. |
| RegistrationsBaseUrl | Sí. | Obtiene los metadatos del paquete. |
| ReportAbuseUriTemplate | no | Cree una dirección URL para acceder a una página web de informe de abuso. |
| RepositorySignatures | no | Obtenga los certificados usados para la firma del repositorio. |
| SearchAutocompleteService | no | Detectar los IDs y las versiones del paquete por subcadena. |
| SearchQueryService | Sí. | Filtre y busque paquetes por palabra clave. |
| SymbolPackagePublish | no | Insertar paquetes de símbolos. |
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 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, el cliente de NuGet oficial vuelve a la dirección URL de abuso de informe de nuget.org (de la que realiza un seguimiento ReportAbuseUriTemplateReportAbuseUriTemplate Otros clientes pueden optar simplemente por no mostrar una dirección URL de abuso de informe al usuario.
Recursos no documentados en nuget.org
El índice de servicio V3 en nuget.org tiene algunos recursos que no están documentados anteriormente. Hay algunas razones para no documentar un recurso.
En primer lugar, no documenta los recursos que se usan como un detalle de implementación de nuget.org. se SearchGalleryQueryService 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 los 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 los recursos que están estrechamente acoplados con el protocolo V2, que a su vez no está documentado intencionadamente. El LegacyGallery recurso 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 nuget.exe list .
Si un recurso no está documentado aquí, se recomienda encarecidamente no tener una dependencia 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 la representación ISO 8601.
Métodos HTTP
| Verbo | Uso |
|---|---|
| GET | 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 elimina la lista de un recurso. |
Códigos de estado HTTP
| Código | Descripción |
|---|---|
| 200 | Correcto y hay un cuerpo de respuesta. |
| 201 | Correcto y se creó el recurso. |
| 202 | La solicitud se ha aceptado correctamente, pero es posible que algún trabajo esté incompleto y completado de forma asincrónica. |
| 204 | Correcto, pero no hay cuerpo de 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 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 Location encabezado y emitiendo un subsiguiente GET . La documentación relativa a puntos de conexión específicos no llamará explícitamente a dónde se pueden usar redireccionamientos.
En el caso de un código de estado de nivel 500, el cliente puede implementar un mecanismo de reintento razonable. El cliente de NuGet oficial vuelve a insondar tres veces al encontrar cualquier código de estado de nivel 500 o error TCP/DNS.
Encabezados de solicitud HTTP
| Nombre | Descripción |
|---|---|
| X-NuGet-ApiKey | Obligatorio para inserción y eliminación, consulte recurso. |
| X-NuGet-Client-Version | En desuso y reemplazado por |
| X-NuGet-Protocol-Version | Obligatorio en determinados casos solo en nuget.org, consulte nuget.org protocolos. |
| X-NuGet-Session-Id | Opcional. NuGet clientes v4.7+ identifican las solicitudes HTTP que forman parte de la misma sesión NuGet cliente. |
tiene X-NuGet-Session-Id un valor único para todas las operaciones relacionadas con una restauración única en PackageReference . En otros escenarios, como autocompletar y restaurar, puede haber varios identificadores de sesión diferentes debido a cómo packages.config se factorizó el código.
Authentication
La autenticación se deja en la implementación de origen del paquete que se va a definir. Por nuget.org, solo el recurso PackagePublish requiere autenticación a través de un encabezado de clave de API especial. Consulte el recurso para obtener más información.