API du serveur NuGet

L’API du serveur NuGet est un ensemble de points de terminaison HTTP qui peuvent être utilisés pour télécharger des packages, extraire 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.exeet 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 dans certains cas que 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 est appelé d’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’usage.

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 d’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 possède un numéro de version majeur de 3. À mesure que les modifications non cassants sont apportées 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 on.

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
catalogue	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	Packages push-and-delete (ou unlist)
ReadmeUriTemplate	Non	Créez une URL pour accéder à README d’un package.
RegistrationsBaseUrl	oui	Obtenir les métadonnées du package.
ReportAbuseUriTemplate	Non	Créez une URL pour accéder à une page web d’abus de rapport.
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 sous-chaîne.
SearchQueryService	oui	Filtrez et recherchez des packages par mot clé.
SymbolPackagePublish	Non	Envoyer (push) 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 rubriques répertoriées 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 une preuve future, 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.

Note

Lorsqu’une source n’implémente pas SearchAutocompleteService tout comportement de saisie semi-automatique doit être désactivé correctement. Quand ReportAbuseUriTemplate n’est pas implémentée, le client NuGet officiel revient à l’URL d’abus de rapport nuget.org (suivie par NuGet/Home#4924). D’autres clients peuvent choisir de ne pas afficher simplement une URL d’abus de rapport à 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. La SearchGalleryQueryService se trouve 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 d’extensibilité 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 appartiennent à 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 fortement vous recommandons de ne pas les 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.

Timestamps

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

Méthodes HTTP

Verbe	Utiliser
AVOIR	Effectue une opération en lecture seule, généralement la récupération des données.
TÊTE	Récupère les en-têtes de réponse pour la demande de GET correspondante.
METTRE	Crée une ressource qui n’existe pas ou, s’il existe, la met à jour. Certaines ressources peuvent ne pas prendre en charge la mise à jour.
SUPPRIMER	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 création de la ressource.
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	Redirection permanente.
302	Redirection temporaire.
400	Les paramètres de l’URL ou du corps de la requête ne sont pas valides.
401	Les informations d’identification fournies ne sont pas valides.
403	L’action n’est pas autorisée en fonction des informations d’identification fournies.
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 n’est pas disponible temporairement.

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 une GETultérieure. 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 d’état 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 requête HTTP

Nom	Description
X-NuGet-ApiKey	Obligatoire pour l’envoi et la suppression, consultez PackagePublish de ressources
X-NuGet -Client-Version	déprécié et remplacé par X-NuGet-Protocol-Version
X-NuGet -Protocol-Version	Obligatoire dans certains cas uniquement sur nuget.org, consultez nuget.org protocoles
X-NuGet -Session-Id	facultatif . Les clients NuGet v4.7+ identifient les requêtes 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 restauration unique dans PackageReference. Pour d’autres scénarios tels que la saisie semi-automatique 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 l’authentification via un en-tête de clé API spécial. Pour plus d’informations, consultez PackagePublish ressource.