API du serveur NuGet

  • Article

L’API du serveur NuGet est un ensemble de points de terminaison HTTP qui peuvent être utilisés pour télécharger des packages, récupérer des métadonnées, publier de nouveaux packages et effectuer la plupart des autres opérations disponibles dans les clients NuGet officiels.

Cette API est utilisée par le client NuGet dans Visual Studio, nuget.exe et l’interface CLI .NET pour effectuer des opérations NuGet telles que dotnet restore, rechercher dans l’interface utilisateur de Visual Studio et nuget.exe push.

Notez que, dans certains cas, nuget.org a des exigences supplémentaires qui ne sont pas appliquées par d’autres sources de package. Ces différences sont documentées par les protocoles nuget.org.

Pour obtenir une énumération et un téléchargement simples des versions de nuget.exe disponibles, consultez le point de terminaison tools.json.

Si vous implémentez un référentiel de packages NuGet, consultez également le guide d’implémentation pour obtenir des exigences et des recommandations supplémentaires.

Index de service

Le point d’entrée de l’API est un document JSON dans un emplacement bien connu. Ce document s’appelle l’index de service. L’emplacement de l’index de service pour nuget.org est https://api.nuget.org/v3/index.json.

Ce document JSON contient une liste de ressources qui fournissent différentes fonctionnalités et répondent à différents cas d'utilisation.

Les clients qui prennent en charge l’API doivent accepter une ou plusieurs de ces URL d’index de service comme moyen de se connecter aux sources de package respectives.

Pour plus d’informations sur l’index de service, consultez sa référence API.

Contrôle de version

L’API est la version 3 du protocole HTTP de NuGet. Ce protocole est parfois appelé « l’API V3 ». Ces documents de référence font référence à cette version du protocole simplement comme « l’API ».

La version du schéma d’index de service est indiquée par la propriété version dans l’index de service. L’API impose que la chaîne de version ait un numéro de version majeur de 3. À mesure que les changements non cassants sont apportés au schéma d’index de service, la version mineure de la chaîne de version sera augmentée.

Les clients plus anciens (tels que nuget.exe 2.x) ne prennent pas en charge l’API V3 et prennent uniquement en charge l’ancienne API V2, qui n’est pas documentée ici.

L’API NuGet V3 est nommée comme telle car elle est le successeur de l’API V2, qui était le protocole OData implémenté par la version 2.x du client NuGet officiel. L’API V3 a d’abord été prise en charge par la version 3.0 du client NuGet officiel et est toujours la dernière version de protocole majeure prise en charge par le client NuGet, 4.0 et les versions supérieures.

Les modifications de protocole non cassants ont été apportées à l’API depuis sa première publication.

Ressources et schéma

L’index de service décrit une variété de ressources. L’ensemble actuel de ressources prises en charge est le suivant :

Nom de la ressource Obligatoire Description
Catalog non Enregistrement complet de tous les événements de package.
PackageBaseAddress Oui Obtenir le contenu du package (.nupkg).
PackageDetailsUriTemplate non Créez une URL pour accéder à une page web de détails de package.
PackagePublish Oui Envoyez et supprimez (ou retirez de la liste) des packages.
RegistrationsBaseUrl Oui Obtenir les métadonnées de package.
ReportAbuseUriTemplate non Créez une URL pour accéder à une page web de signalement d’un abus.
RepositorySignatures non Obtenir des certificats utilisés pour la signature du référentiel.
SearchAutocompleteService non Découvrez les ID de package et les versions par substring.
SearchQueryService Oui Filtrez et recherchez des packages par mot clé.
SymbolPackagePublish non Envoyer des packages de symboles.
VulnerabilityInfo non Packages avec vulnérabilités connues.

En général, toutes les données non binaires retournées par une ressource d’API sont sérialisées à l’aide de JSON. Le schéma de réponse retourné par chaque ressource dans l’index de service est défini individuellement pour cette ressource. Pour plus d’informations sur chaque ressource, consultez les topics répertoriés ci-dessus.

À l’avenir, à mesure que le protocole évolue, de nouvelles propriétés peuvent être ajoutées aux réponses JSON. Pour que le client soit à l'épreuve du temps, l’implémentation ne doit pas supposer que le schéma de réponse est final et ne peut pas inclure de données supplémentaires. Toutes les propriétés que l’implémentation ne comprend pas doivent être ignorées.

Remarque

Lorsqu’une source n’implémente SearchAutocompleteService aucun comportement d’autocomplétion doit être désactivé correctement. Lorsqu’il ReportAbuseUriTemplate n’est pas implémenté, le client NuGet officiel revient à l’URL de signalement d’un abus de nuget.org (suivi par NuGet/Home#4924). D’autres clients peuvent choisir de ne pas afficher simplement une URL de signalement d’un abus à l’utilisateur.

Ressources non documentées sur nuget.org

L’index de service V3 sur nuget.org contient certaines ressources qui ne sont pas documentées ci-dessus. Il existe quelques raisons de ne pas documenter une ressource.

Tout d’abord, nous ne documentons pas les ressources utilisées comme détail d’implémentation de nuget.org. Le SearchGalleryQueryService chute dans cette catégorie. NuGetGallery utilise cette ressource pour déléguer certaines requêtes V2 (OData) à notre index de recherche au lieu d’utiliser la base de données. Cette ressource a été introduite pour des raisons de scalabilité et n’est pas destinée à une utilisation externe.

Deuxièmement, nous ne documentons pas les ressources qui n’ont jamais été livrées dans une version RTM du client officiel. PackageDisplayMetadataUriTemplate et PackageVersionDisplayMetadataUriTemplate entrent dans cette catégorie.

Troisièmement, nous ne documentons pas les ressources étroitement couplées au protocole V2, qui est intentionnellement non documenté. La ressource LegacyGallery se trouve dans cette catégorie. Cette ressource permet à un index de service V3 de pointer vers une URL source V2 correspondante. Cette ressource prend en charge le nuget.exe list.

Si une ressource n’est pas documentée ici, nous vous recommandons vivement de ne pas en dépendre. Nous pouvons supprimer ou modifier le comportement de ces ressources non documentées, ce qui peut interrompre votre implémentation de manière inattendue.

Horodatages

Tous les horodatages retournés par l’API sont UTC ou sont spécifiés à l’aide de la représentation ISO 8601.

Méthodes HTTP

Verbe Utiliser
GET Effectue une opération en lecture seule, généralement la récupération des données.
HEAD Récupère les en-têtes de réponse pour la requête GET correspondante.
PUT Crée une ressource qui n’existe pas ou, si elle existe, la met à jour. Certaines ressources peuvent ne pas prendre en charge la mise à jour.
DELETE Supprime ou supprime une ressource.

Codes d’état HTTP

Code Description
200 Réussite, et il y a un corps de réponse.
201 Réussite et la ressource a été créée.
202 Réussite, la demande a été acceptée, mais certains travaux peuvent toujours être incomplets et terminés de manière asynchrone.
204 Réussite, mais il n’y a pas de corps de réponse.
301 Une redirection permanente.
302 Une redirection temporaire.
400 Les paramètres de l’URL ou du corps de la demande ne sont pas valides.
401 Les identifiants fournis ne sont pas valides.
403 L’action n’est pas autorisée en fonction des identifiants fournis.
404 La ressource demandée n’existe pas.
409 La requête est en conflit avec une ressource existante.
500 Le service a rencontré une erreur inattendue.
503 Le service est temporairement indisponible.

Toute requête GET adressée à un point de terminaison d’API peut retourner une redirection HTTP (301 ou 302). Les clients doivent gérer correctement ces redirections en observant l’en-tête Location et en émettant un autre GET. La documentation concernant des points de terminaison spécifiques n’appelle pas explicitement où les redirections peuvent être utilisées.

Dans le cas d’un code de statut de 500 niveaux, le client peut implémenter un mécanisme de nouvelle tentative raisonnable. Le client NuGet officiel retente trois fois lors de la rencontre d’une erreur d’état de niveau 500 ou TCP/DNS.

En-têtes de demande HTTP

Nom Description
X-NuGet-ApiKey Obligatoire pour l’envoi et la suppression, consultez la PackagePublishressource
X-NuGet-Client-Version Déconseillé et remplacé par X-NuGet-Protocol-Version
X-NuGet-Protocol-Version Obligatoire dans certains cas uniquement sur nuget.org, consultez les protocoles nuget.org
X-NuGet-Session-Id Facultatif. Les clients NuGet v4.7+ identifient les demandes HTTP qui font partie de la même session cliente NuGet.

Le X-NuGet-Session-Id a une valeur unique pour toutes les opérations liées à une seule restauration dans PackageReference. Pour d’autres scénarios tels que l’autocomplétion et la restauration packages.config, il peut y avoir plusieurs ID de session différents en raison de la façon dont le code est factorisé.

Authentification

L’authentification est laissée à l’implémentation source du package pour définir. Pour nuget.org, seule la ressource PackagePublish nécessite une authentification via un en-tête de clé API spéciale. Pour plus d’informations, consultez PackagePublish la ressource.