Ancien guide de l’API v3 SUSE Rancher Prime

L’API v3 précédente a sa propre interface utilisateur accessible depuis un navigateur web. C’est un moyen facile de voir les ressources, d’effectuer des actions et de voir l’équivalent curl ou la requête et la réponse HTTP. Pour y accéder :

Les requêtes API doivent inclure des informations d’authentification. L’authentification se fait par authentification de base HTTP en utilisant rancher-admin/users/settings/api-keys.adoc[clés API]. Les clés API peuvent créer de nouveaux clusters et avoir accès à plusieurs clusters via /v3/clusters/. Les rôles de cluster et de projet s’appliquent à ces clés et restreignent les clusters et projets que le compte peut voir ainsi que les actions qu’il peut effectuer.

Par défaut, certains tokens API au niveau du cluster sont générés avec un temps de vie infini (ttl=0). En d’autres termes, les tokens API avec ttl=0 n’expirent jamais à moins que vous ne les invalidiez. Pour des détails sur la façon de les invalider, reportez-vous à la page des tokens API.

L’API est généralement RESTful mais possède plusieurs fonctionnalités pour rendre la définition de tout découvrable par un client afin que des clients génériques puissent être écrits au lieu d’avoir à écrire un code spécifique pour chaque type de ressource. Pour des informations détaillées sur la spécification API générique, voir la documentation complémentaire.

La conception vous permet de charger uniquement la liste des schémas et d’accéder à tout ce qui concerne l’API. L’interface utilisateur de l’API ne contient aucun code spécifique à Rancher lui-même. L’URL pour obtenir les schémas est envoyée dans chaque réponse HTTP en tant qu’en-tête X-Api-Schemas. À partir de là, vous pouvez suivre le lien collection sur chaque schéma pour savoir où lister les ressources, et suivre d’autres links à l’intérieur des ressources retournées pour obtenir d’autres informations.

En pratique, vous voudrez peut-être simplement construire des chaînes d’URL. Nous vous conseillons fortement de limiter cela au niveau supérieur pour lister une collection (/v3/<type>) ou obtenir une ressource spécifique (/v3/<type>/<id>). Tout ce qui est plus profond que cela est susceptible de changer dans les futures versions.

Les ressources ont des relations entre elles appelées liens. Chaque ressource inclut une carte de links avec le nom du lien et l’URL où vous pouvez récupérer cette information. Encore une fois, vous devriez GET la ressource puis suivre l’URL dans la carte links, et non pas construire ces chaînes vous-même.

La plupart des ressources ont des actions, qui font quelque chose ou changent l’état de la ressource. Pour les utiliser, envoyez un POST HTTP à l’URL dans la carte actions de l’action que vous souhaitez. Certaines actions nécessitent une entrée ou produisent une sortie. Consultez la documentation individuelle pour chaque type ou les schémas pour des informations spécifiques.

Pour modifier une ressource, envoyez un HTTP PUT au lien links.update sur la ressource avec les champs que vous souhaitez changer. Si le lien est manquant, alors vous n’avez pas la permission de mettre à jour la ressource. Les champs inconnus et ceux qui ne sont pas modifiables sont ignorés.

Pour supprimer une ressource, envoyez un HTTP DELETE au lien links.remove sur la ressource. Si le lien est manquant, alors vous n’avez pas la permission de mettre à jour la ressource.

Pour créer une nouvelle ressource, envoyez un HTTP POST à l’URL de la collection dans le schéma (qui est /v3/<type>).

La plupart des collections peuvent être filtrées côté serveur par des champs communs en utilisant des paramètres de requête HTTP. La carte filters vous montre quels champs peuvent être filtrés et quelles étaient les valeurs filtrées pour la requête que vous avez faite. L’interface API dispose de contrôles pour configurer le filtrage et vous montrer la requête appropriée. Pour des correspondances simples "égale", c’est juste field=value. Des modificateurs peuvent être ajoutés au nom du champ, par exemple, field_gt=42 pour "le champ est supérieur à 42." Consultez la spécification API pour plus de détails.

La plupart des collections peuvent être triées côté serveur par des champs communs en utilisant des paramètres de requête HTTP. La carte sortLinks vous montre quels tris sont disponibles, ainsi que l’URL pour obtenir la collection triée en fonction de celui-ci. Elle inclut également des informations sur ce par quoi la réponse actuelle a été triée, si spécifié.

Les réponses de l’API sont paginées avec une limite de 100 ressources par page par défaut. Cela peut être changé avec le paramètre de requête limit, jusqu’à un maximum de 1000, par exemple, /v3/pods?limit=1000. La carte pagination dans les réponses de collection vous indique si vous avez ou non l’ensemble complet des résultats et contient un lien vers la page suivante si ce n’est pas le cas.

Vous pouvez utiliser les outils de développement du navigateur pour capturer comment l’API v3 est appelée. Par exemple, vous pourriez suivre ces étapes pour utiliser les outils de développement Chrome afin d’obtenir l’appel API pour provisionner un cluster de distribution Kubernetes Rancher :