SDK clients

Plutôt que d'écrire les appels HTTP à la main, utilisez un client généré. Trois sont produits depuis le contrat publié — C#, TypeScript et Python — de sorte que leurs types correspondent toujours à ce que l'API sert réellement.

Les obtenir

Les SDK sont pour l'instant distribués sous forme d'artefacts de build, pas depuis un registry de paquets. Demandez à votre interlocuteur Staff & Go l'archive correspondant à la version de contrat que vous intégrez ; chacune porte un fichier VERSION qui l'identifie.

Cela va changer. La publication sur des registries publics — Sonatype OSS, npm, PyPI — est l'étape suivante prévue, pour qu'installer un client tienne en une ligne de commande. D'ici là, l'artefact est la voie supportée. Si la publication en registry pèse sur votre calendrier, dites-le : c'est une question de priorisation, pas un obstacle technique.

Utiliser un client

Chaque client est un arbre fluide qui reproduit la structure des URL. Lire un profil partenaire donne ceci :

var profile = await client.Api.V1.Client.Partner.Profile.GetAsync();

const profile = await client.api.v1.client.partner.profile.get();

profile = await client.api.v1.client.partner.profile.get()

La version fait partie de ce chemin, exactement comme dans l'URL — passer de v1 à v2 est donc une modification visible et délibérée, jamais un changement de comportement silencieux. Voir Versionnement.

Deux choses à régler vous-même

L'URL de base. Le contrat ne déclare aucun serveur : le client ne peut pas deviner l'environnement que vous visez. Renseignez-la explicitement à la construction de l'adaptateur de requêtes — c'est aussi ce qui évite qu'une seule erreur de configuration ne sépare le bac à sable de la production.

L'authentification. Les clients générés n'émettent pas de jetons. Fournissez le bearer token via le fournisseur d'authentification de votre pile HTTP, en le renouvelant avant expiration comme décrit dans Authentification.

Ce que les clients générés ne couvrent pas

Ils parlent le contrat, et rien au-delà. Ces points restent à votre charge, et chacun a son guide :

Régénérer un client vous-même

Rien ne l'empêche : le contrat est public à /openapi/v1.json et le générateur est Kiota, gratuit et open source. Générer le vôtre est une option légitime s'il vous faut un langage que nous ne publions pas, ou d'autres conventions.