Service index

Index služby je dokument JSON, který je vstupním bodem zdroje balíčku NuGet a umožňuje implementaci klienta zjistit možnosti zdroje balíčku. Index služby je objekt JSON se dvěma požadovanými vlastnostmi: version (verze schématu indexu služby) a resources (koncové body nebo možnosti zdroje balíčku).

Index služby nuget.org se nachází na adrese https://api.nuget.org/v3/index.json.

Versioning

Hodnota version je řetězec parsovatelné verze SemVer 2.0.0, který označuje verzi schématu indexu služby. Rozhraní API vyžaduje, aby řetězec verze má číslo hlavní verze 3. Vzhledem k tomu, že ve schématu indexu služby se neprovedou změny způsobující chybu, zvýší se podverze řetězce verze.

Každý prostředek v indexu služby má verzi nezávisle na verzi schématu indexu služby.

Aktuální verze schématu je 3.0.0. Verze 3.0.0 je funkčně ekvivalentní starší 3.0.0-beta.1 verzi, ale měla by být upřednostňovaná, protože jasněji komunikuje se stabilním definovaným schématem.

HTTP methods

Index služby je přístupný pomocí metod GET HTTP a HEAD.

Resources

Vlastnost resources obsahuje pole prostředků podporovaných tímto zdrojem balíčku.

Resource

Prostředek je objekt v resources poli. Představuje funkci verze zdroje balíčku. Prostředek má následující vlastnosti:

Name	Typ	Required	Notes
@id	řetězec	yes	Adresa URL prostředku
@type	řetězec	yes	Řetězcová konstanta představující typ prostředku
komentář	řetězec	no	Popis zdroje čitelný pro člověka

Jedná se @id o adresu URL, která musí být absolutní a musí mít buď schéma HTTP nebo HTTPS.

Slouží @type k identifikaci konkrétního protokolu, který se má použít při interakci s prostředkem. Typ prostředku je neprůrůzný řetězec, ale obecně má formát:

{RESOURCE_NAME}/{RESOURCE_VERSION}

Očekává se, že klienti pevně zakódují @type hodnoty, kterým rozumí, a vyhledávají je v indexu služby zdroje balíčků. Přesné @type hodnoty, které se dnes používají, jsou uvedeny v referenčních dokumentech jednotlivých prostředků uvedených v přehledu rozhraní API.

V zájmu této dokumentace bude dokumentace o různých prostředcích v podstatě seskupena {RESOURCE_NAME} podle indexu služby, který je podobný seskupení podle scénáře.

Neexistuje žádný požadavek, aby každý prostředek má jedinečný @id nebo @type. Záleží na implementaci klienta, aby bylo možné určit, který prostředek má přednost před jiným. Jednou z možných implementací je to, že prostředky stejné nebo kompatibilní @type lze použít v případě selhání připojení nebo chyby serveru pomocí kruhového dotazování.

Prostředek může používat jiného hostitele nebo domény než index služby, ale to může způsobit problémy v prostředích s přísnými pravidly sítě. Konkrétně pokud index služby přidá prostředky, které odkazují přímo na nuget.org (místo proxy serveru nebo ukládání do mezipaměti prostřednictvím vlastního informačního kanálu), nebude váš informační kanál fungovat tam, kde je zablokovaný přístup k nuget.org. Pokud váš informační kanál bude delegovat konkrétní prostředky na nuget.org, doporučujeme přidat konfiguraci, aby se při nasazení informačního kanálu mohly odebrat přímé nuget.org reference z indexu služby.

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."
    }
  ]
}