API Server NuGet

L'API del server NuGet è un set di endpoint HTTP che possono essere usati per scaricare pacchetti, recuperare metadati, pubblicare nuovi pacchetti ed eseguire la maggior parte delle altre operazioni disponibili nei client NuGet ufficiali.

Questa API viene usata dal client NuGet in Visual Studio, nuget.exe e dall'interfaccia della riga di comando di .NET per eseguire operazioni NuGet, dotnet restoread esempio , eseguire ricerche nell'interfaccia utente di Visual Studio e nuget.exe push.

Si noti che in alcuni casi nuget.org presenta requisiti aggiuntivi non applicati da altre origini del pacchetto. Queste differenze sono documentate dai protocolli di nuget.org.

Per un'enumerazione semplice e il download delle versioni di nuget.exe disponibili, vedere l'endpoint tools.json .

Se si implementa un repository di pacchetti NuGet, vedere anche la guida all'implementazione per altri requisiti e consigli.

Indice dei servizi

Il punto di ingresso per l'API è un documento JSON in una posizione nota. Questo documento è denominato indice del servizio. La posizione dell'indice del servizio per nuget.org è https://api.nuget.org/v3/index.json.

Questo documento JSON contiene un elenco di risorse che forniscono funzionalità diverse e soddisfano casi d'uso diversi.

I client che supportano l'API devono accettare uno o più di questi URL di indice del servizio come mezzo per connettersi alle rispettive origini del pacchetto.

Per altre informazioni sull'indice del servizio, vedere le informazioni di riferimento sulle API.

Controllo delle versioni

L'API è la versione 3 del protocollo HTTP di NuGet. Questo protocollo viene talvolta definito "API V3". Questi documenti di riferimento fanno riferimento a questa versione del protocollo semplicemente come "l'API".

La versione dello schema dell'indice del servizio è indicata dalla version proprietà nell'indice del servizio. L'API impone che la stringa di versione abbia un numero di versione principale di 3. Man mano che vengono apportate modifiche non di rilievo allo schema dell'indice del servizio, la versione secondaria della stringa di versione verrà aumentata.

I client meno recenti (ad esempio nuget.exe 2.x) non supportano l'API V3 e supportano solo l'API V2 precedente, non documentata qui.

L'API NuGet V3 è denominata come tale perché è il successore dell'API V2, che era il protocollo basato su OData implementato dalla versione 2.x del client NuGet ufficiale. L'API V3 è stata supportata per la prima volta dalla versione 3.0 del client NuGet ufficiale ed è ancora la versione del protocollo principale più recente supportata dal client NuGet, 4.0 e on.

Le modifiche al protocollo non di rilievo sono state apportate all'API dalla prima versione.

Risorse e schema

L'indice del servizio descrive un'ampia gamma di risorse. Il set corrente di risorse supportate è il seguente:

Nome risorsa	Richiesto	Descrizione
Catalog	no	Record completo di tutti gli eventi del pacchetto.
PackageBaseAddress	yes	Ottenere il contenuto del pacchetto (.nupkg).
PackageDetailsUriTemplate	no	Creare un URL per accedere a una pagina Web dei dettagli del pacchetto.
PackagePublish	yes	Eseguire il push e l'eliminazione di pacchetti (o annullare l'elenco).
RegistrationsBaseUrl	yes	Ottenere i metadati del pacchetto.
ReportAbuseUriTemplate	no	Creare un URL per accedere a una pagina Web di abuso di report.
RepositorySignatures	no	Ottenere i certificati usati per la firma del repository.
SearchAutocompleteService	no	Individuare gli ID e le versioni dei pacchetti tramite sottostringa.
SearchQueryService	yes	Filtrare e cercare pacchetti per parola chiave.
SymbolPackagePublish	no	Eseguire il push dei pacchetti di simboli.
VulnerabilityInfo	no	Pacchetti con vulnerabilità note.

In generale, tutti i dati non binari restituiti da una risorsa API vengono serializzati tramite JSON. Lo schema di risposta restituito da ogni risorsa nell'indice del servizio viene definito singolarmente per tale risorsa. Per altre informazioni su ogni risorsa, vedere gli argomenti elencati in precedenza.

In futuro, man mano che il protocollo evolve, è possibile aggiungere nuove proprietà alle risposte JSON. Affinché il client sia di prova futura, l'implementazione non deve presupporre che lo schema di risposta sia finale e non possa includere dati aggiuntivi. Tutte le proprietà che l'implementazione non riconosce devono essere ignorate.

Nota

Quando un'origine non implementa SearchAutocompleteService alcun comportamento di completamento automatico deve essere disabilitato normalmente. Quando ReportAbuseUriTemplate non viene implementato, il client NuGet ufficiale esegue il fallback all'URL dell'abuso di report di nuget.org (rilevato da NuGet/Home#4924). Altri client possono scegliere di non visualizzare semplicemente un URL di abuso di report per l'utente.

Risorse non documentate in nuget.org

L'indice del servizio V3 in nuget.org include alcune risorse non documentate in precedenza. Esistono alcuni motivi per cui non è possibile documentare una risorsa.

In primo luogo, non vengono documentato le risorse usate come dettaglio di implementazione di nuget.org. Rientra SearchGalleryQueryService in questa categoria. NuGetGallery usa questa risorsa per delegare alcune query V2 (OData) all'indice di ricerca anziché usare il database. Questa risorsa è stata introdotta per motivi di scalabilità e non è destinata all'uso esterno.

In secondo luogo, non vengono documentate le risorse mai spedite in una versione RTM del client ufficiale. PackageDisplayMetadataUriTemplate e PackageVersionDisplayMetadataUriTemplate rientrano in questa categoria.

In terzo luogo, non vengono documentate le risorse strettamente associate al protocollo V2, che è intenzionalmente non documentato. La LegacyGallery risorsa rientra in questa categoria. Questa risorsa consente a un indice del servizio V3 di puntare a un URL di origine V2 corrispondente. Questa risorsa supporta .nuget.exe list

Se una risorsa non è documentata qui, è consigliabile non assumerne una dipendenza. È possibile rimuovere o modificare il comportamento di queste risorse non documentate che potrebbero interrompere l'implementazione in modi imprevisti.

Timestamp

Tutti i timestamp restituiti dall'API sono UTC o vengono specificati in altro modo usando la rappresentazione ISO 8601 .

Metodi HTTP

Verbo	Utilizzo
GET	Esegue un'operazione di sola lettura, in genere recuperando i dati.
HEAD	Recupera le intestazioni di risposta per la richiesta corrispondente GET .
PUT	Crea una risorsa che non esiste o, se esiste, la aggiorna. Alcune risorse potrebbero non supportare l'aggiornamento.
DELETE	Elimina o annulla l'elenco di una risorsa.

Codici di stato HTTP

Codice	Descrizione
200	Il successo e c'è un corpo della risposta.
201	Operazione riuscita e creazione della risorsa.
202	Esito positivo, la richiesta è stata accettata, ma alcune operazioni potrebbero essere ancora incomplete e completate in modo asincrono.
204	Il successo, ma non c'è alcun corpo della risposta.
301	Reindirizzamento permanente.
302	Reindirizzamento temporaneo.
400	I parametri nell'URL o nel corpo della richiesta non sono validi.
401	Le credenziali specificate non sono valide.
403	L'azione non è consentita in base alle credenziali specificate.
404	La risorsa richiesta non esiste.
409	La richiesta è in conflitto con una risorsa esistente.
500	Il servizio ha rilevato un errore imprevisto.
503	Il servizio è temporaneamente non disponibile.

Qualsiasi GET richiesta effettuata a un endpoint API può restituire un reindirizzamento HTTP (301 o 302). I client devono gestire correttamente tali reindirizzamenti osservando l'intestazione Location e emettendo un oggetto successivo GET. La documentazione relativa a endpoint specifici non chiamerà in modo esplicito dove possono essere usati i reindirizzamenti.

Nel caso di un codice di stato a 500 livelli, il client può implementare un meccanismo di ripetizione ragionevole. Il client NuGet ufficiale ritenta tre volte quando viene rilevato un codice di stato a 500 livelli o un errore TCP/DNS.

Intestazioni di richiesta HTTP

Nome	Descrizione
X-NuGet-ApiKey	Obbligatorio per il push e l'eliminazione, vedere PackagePublish la risorsa
X-NuGet-Client-Version	Deprecato e sostituito da X-NuGet-Protocol-Version
X-NuGet-Protocol-Version	Obbligatorio in alcuni casi solo in nuget.org, vedere protocolli nuget.org
X-NuGet-Session-Id	Facoltativo. I client NuGet v4.7+ identificano le richieste HTTP che fanno parte della stessa sessione client NuGet.

ha X-NuGet-Session-Id un singolo valore per tutte le operazioni correlate a un singolo ripristino in PackageReference. Per altri scenari, ad esempio il completamento automatico e packages.config il ripristino, potrebbero essere presenti diversi ID sessione a causa della modalità di factoring del codice.

Autenticazione

L'autenticazione viene lasciata all'implementazione dell'origine del pacchetto da definire. Per nuget.org, solo la PackagePublish risorsa richiede l'autenticazione tramite un'intestazione di chiave API speciale. Per informazioni dettagliate, vedere PackagePublish la risorsa .