Index de service

Article
12/22/2023

L’index de service est un document JSON qui est le point d’entrée d’une source de package NuGet et permet à une implémentation du client de découvrir les fonctionnalités de la source de package. L’index de service est un objet JSON avec deux propriétés requises : version (version de schéma de l’index de service) et resources (points de terminaison ou fonctionnalités de la source du package).

L’index de service de nuget.org se trouve à https://api.nuget.org/v3/index.json.

Contrôle de version

La valeur version est une chaîne de version parseable SemVer 2.0.0 qui indique la version de schéma de l’index de service. L’API impose que la chaîne de version ait un numéro de version majeur de 3. À mesure que les changements non cassants sont apportés au schéma d’index de service, la version mineure de la chaîne de version sera augmentée.

Chaque ressource de l’index de service est versionnée indépendamment de la version du schéma d’index de service.

La version actuelle du schéma est 3.0.0. La version 3.0.0 est fonctionnellement équivalente à l’ancienne version 3.0.0-beta.1, mais elle doit être préférée, car elle communique plus clairement le schéma stable et défini.

Méthodes HTTP

L’index de service est accessible à l’aide des méthodes HTTP GET et HEAD.

Ressources

La propriété resources contient un tableau de ressources prises en charge par cette source de package.

Ressource

Une ressource est un objet dans le tableau resources. Il représente une fonctionnalité avec version d’une source de package. Une ressource a les propriétés suivantes :

Nom	Type	Requise	Notes
@id	string	Oui	URL de la ressource
@type	string	Oui	Constante de chaîne représentant le type de ressource.
commentaire	string	non	Une description de la ressource lisible par l'utilisateur

Le @id est une URL qui doit être absolue et doit avoir le schéma HTTP ou HTTPS.

Le @type est utilisé pour identifier le protocole spécifique à utiliser lors de l’interaction avec la ressource. Le type de la ressource est une chaîne opaque, mais a généralement le format suivant :

{RESOURCE_NAME}/{RESOURCE_VERSION}

Les clients doivent coder en dur les valeurs @type qu’ils comprennent et recherchent dans l’index de service d’une source de package. Les valeurs exactes @type utilisées aujourd’hui sont énumérées sur les documents de référence de ressources individuels répertoriés dans la vue d’ensemble de l’API.

Dans le cadre de cette documentation, la documentation sur les différentes ressources sera essentiellement regroupée par le {RESOURCE_NAME} dans l’index de service qui est analogue au regroupement par scénario.

Il n’est pas nécessaire que chaque ressource ait une ressource unique @id ou @type. Il incombe à l’implémentation du client de déterminer la ressource à préférer à une autre. Une implémentation possible est que les ressources du même @type ou d’un compatible peuvent être utilisées à la manière d’un tourniquet en cas d’échec de connexion ou d’erreur de serveur.

Exemple de requête

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

Exemple de réponse

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

Partager via