L'API que la console utilise.
La console NoryxLab est un client de la meme API que vos integrations. Le contrat public est versionne, decrit par OpenAPI et servi directement par chaque instance.
Un contrat public, et des routes internes
Deux specifications sont produites depuis le routeur et verifiees par la CI. Utilisez exclusivement le document public pour une integration. Les routes internes existent pour le fonctionnement de la console et les operations de plateforme ; elles peuvent changer sans preavis.
/swagger/openapi.public.yamlContrat supporte pour les integrations./swagger/openapi.yamlDiagnostic et lecture interne ; les routes internes portent x-noryx-internal: true./swaggerExploration interactive de la specification publique, servie localement.Aucune requete ne quitte votre installation pour afficher Swagger. C'est important pour les environnements isoles du reseau internet.
Decouvrir votre instance
Remplacez https://datalab.example.org par l'URL publique de votre instance. Commencez par verifier l'etat de sante, puis telechargez la specification correspondant exactement a la version deployee.
# Etat de l'API curl --fail --silent https://datalab.example.org/healthz # Contrat public OpenAPI curl --fail --remote-name \\ https://datalab.example.org/swagger/openapi.public.yaml # Exploration dans le navigateur open https://datalab.example.org/swagger
La documentation de votre instance est plus importante qu'une copie locale : elle correspond aux routes effectivement servies et a leur version.
Authentifier un appel
Un appel porte un jeton Bearer OIDC. Pour un utilisateur, il provient de la session de votre fournisseur d'identite. Pour une automatisation, utilisez un jeton de service ou un jeton personnel lorsque votre edition et votre politique de plateforme le permettent. Ne placez jamais un jeton dans un depot Git, une image ou une URL.
# Garder le jeton hors de l'historique du shell.
export NORYX_TOKEN='...'
curl --fail --silent \\
-H "Authorization: Bearer ${NORYX_TOKEN}" \\
-H 'Accept: application/json' \\
https://datalab.example.org/api/v1/projects- Le serveur etablit toujours l'identite et les droits depuis le jeton ; les identifiants de projet, workspace ou organisation envoyes par le client ne sont jamais une autorisation.
- Un jeton de script doit etre restreint au projet et a la duree necessaires. Revoquez-le en cas de doute et consignez son proprietaire.
- Les secrets de donnees et de depot restent des secrets distincts du jeton API de NoryxLab.
Utiliser l'API par objets
L'API emploie le meme vocabulaire que la console. Une integration saine traite les projets comme le contexte principal, puis rattache les ressources et les executions a ce projet.
Projets et acces
Creer, lire et administrer les projets, organisations, membres et droits selon le role du demandeur.
Donnees et developpement
Gerer datasets, datasources, depots, secrets, environnements, builds et catalogues semantiques.
Executions
Lancer et suivre workspaces, jobs, jobs planifies, applications et leurs journaux.
Gouvernance
Selon l'edition : audit, sauvegardes, controles de plateforme, politiques et fonctions d'administration.
Si une procedure est definie, automatisez-la avec un job ou un job planifie. Les agents ont un perimetre et des actions fermes ; ils ne remplacent pas une API reproductible.
Regles de compatibilite
- Construisez une integration sur
/api/v1et la specification publique, jamais sur les appels observes dans le navigateur. - Respectez les codes HTTP et les schemas declares ; ne supposez pas qu'un champ interne sera stable.
- Validez votre client contre la specification telechargee de l'instance cible avant une mise en production.
- Utilisez des appels idempotents ou des identifiants de correlation dans vos propres workflows lorsque vous relancez une operation apres une erreur reseau.
- Traitez
401et403comme des erreurs d'identite ou de droit, pas comme une invitation a contourner les controles.