Service index

L'indice del servizio è un documento JSON che rappresenta il punto di ingresso per un'origine del pacchetto NuGet e consente a un'implementazione client di individuare le funzionalità dell'origine del pacchetto. L'indice del servizio è un oggetto JSON con due proprietà obbligatorie: version (la versione dello schema dell'indice del servizio) e resources (gli endpoint o le funzionalità dell'origine del pacchetto).

L'indice del servizio di nuget.org si trova in https://api.nuget.org/v3/index.json.

Versioning

Il version valore è una stringa di versione analizzabile SemVer 2.0.0 che indica la versione dello schema dell'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.

Ogni risorsa nell'indice del servizio viene eseguita in modo indipendente dalla versione dello schema dell'indice del servizio.

La versione corrente dello schema è 3.0.0. La 3.0.0 versione è funzionalmente equivalente alla versione precedente 3.0.0-beta.1 , ma deve essere preferita perché comunica più chiaramente lo schema stabile e definito.

HTTP methods

L'indice del servizio è accessibile tramite metodi GET HTTP e HEAD.

Resources

La resources proprietà contiene una matrice di risorse supportate da questa origine del pacchetto.

Resource

Una risorsa è un oggetto nella resources matrice. Rappresenta una funzionalità con controllo delle versioni di un'origine del pacchetto. Una risorsa ha le proprietà seguenti:

Name	Type	Required	Notes
@id	string	yes	URL della risorsa
@type	string	yes	Costante stringa che rappresenta il tipo di risorsa
comment	string	no	Descrizione leggibile della risorsa

@id è un URL che deve essere assoluto e deve avere lo schema HTTP o HTTPS.

Viene @type usato per identificare il protocollo specifico da usare durante l'interazione con la risorsa. Il tipo della risorsa è una stringa opaca, ma in genere ha il formato:

{RESOURCE_NAME}/{RESOURCE_VERSION}

I client devono impostare come hardcoded i @type valori che comprendono e li cercano nell'indice del servizio di un'origine del pacchetto. I valori esatti @type in uso oggi vengono enumerati nei singoli documenti di riferimento delle risorse elencati nella panoramica dell'API.

Ai fini di questa documentazione, la documentazione relativa alle diverse risorse verrà essenzialmente raggruppata in base all'elemento {RESOURCE_NAME} presente nell'indice del servizio analogo al raggruppamento per scenario.

Non è necessario che ogni risorsa abbia un valore univoco @id o @type. Spetta all'implementazione del client determinare quale risorsa preferire rispetto a un'altra. Una possibile implementazione consiste nel fatto che le risorse della stessa o compatibile @type possono essere usate in modo round robin in caso di errore di connessione o errore del server.

Una risorsa può usare un host o un dominio diverso rispetto all'indice del servizio, ma ciò può causare problemi negli ambienti con regole di rete rigorose. In particolare, se l'indice del servizio aggiunge risorse che puntano direttamente a nuget.org (anziché eseguire il proxy o la memorizzazione nella cache tramite il proprio feed), il feed non funzionerà dove viene bloccato l'accesso a nuget.org. Se il feed delega specifiche risorse a nuget.org, è consigliabile aggiungere una configurazione in modo che, quando il feed viene distribuito, il riferimento diretto nuget.org può essere rimosso dall'indice del servizio.

Sample request

GET https://api.nuget.org/v3/index.json

Sample response

{
  "version": "3.0.0",
  "resources": [
    {
      "@id": "https://api.nuget.org/v3-flatcontainer/",
      "@type": "PackageBaseAddress/3.0.0",
      "comment": "Base URL of Azure storage where NuGet package registration info for NET Core is stored, in the format https://api.nuget.org/v3-flatcontainer/{id-lower}/{id-lower}.{version-lower}.nupkg"
    },
    {
      "@id": "https://www.nuget.org/api/v2/package",
      "@type": "PackagePublish/2.0.0"
    },
    {
      "@id": "https://api-v2v3search-0.nuget.org/query",
      "@type": "SearchQueryService/3.0.0-rc",
      "comment": "Query endpoint of NuGet Search service (primary) used by RC clients"
    },
    {
      "@id": "https://api-v2v3search-0.nuget.org/autocomplete",
      "@type": "SearchAutocompleteService/3.0.0-rc",
      "comment": "Autocomplete endpoint of NuGet Search service (primary) used by RC clients"
    },
    {
      "@id": "https://api.nuget.org/v3/registration2/",
      "@type": "RegistrationsBaseUrl/3.0.0-rc",
      "comment": "Base URL of Azure storage where NuGet package registration info is stored used by RC clients. This base URL does not include SemVer 2.0.0 packages."
    }
  ]
}