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 GET
ulté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.