api

Documentation du serveur web Talaxie Talaxie Web Server Documentation

Consultez vos projets Talaxie, importez des jobs, générez le code et construisez vos jobs par une API HTTP, sans interface graphique. Browse your Talaxie projects, import jobs, generate code and build your jobs through an HTTP API, without a graphical interface.

Vue d'ensemble & UtilisationOverview & Usage

ruxie-server est un exécutable sans fenêtre, livré avec Talaxie. Il permet aux outils et aux pipelines d'intégration continue de lire les projets, d'y importer des jobs, de générer le code Java et de construire les jobs et les routes. Il n'exécute aucun job. Seuls l'import et l'option updateMinor d'une construction modifient les projets. ruxie-server is a windowless executable shipped with Talaxie. It lets tools and continuous integration pipelines read projects, import jobs into them, generate Java code, and build jobs and routes. It does not run any job. Only imports and the updateMinor build option change projects.

Syntaxe & démarrageSyntax & startup

Le port et au moins un projet ou un workspace sont obligatoires. Le jeton est facultatif : The port and at least one project or workspace are required. The token is optional:

ruxie-server --port <port> (--project <dossier> | --workspace <dossier>)... [options]

Exemple avec un jeton choisi (PowerShell) : Example with a chosen token (PowerShell):

$env:RUXIE_SERVER_TOKEN = "un-jeton-long-et-aleatoire"
ruxie-server --port 8787 --workspace C:\Talaxie\workspace

Le serveur reste au premier plan et affiche chaque requête. Ctrl+C l'arrête. The server stays in the foreground and prints each request. Ctrl+C stops it.

Talaxie écoute sur http://127.0.0.1:8787/api/v1
GET /api/v1/projects 200

PrérequisRequirements

  • Un JDK pour la génération et la construction. A JDK for generation and builds.
  • Le dossier codegen à côté de l'exécutable, ou son chemin dans RUXIE_CODEGEN_DIR. Sans lui, le serveur ne démarre pas. The codegen folder next to the executable, or its path in RUXIE_CODEGEN_DIR. Without it, the server does not start.
  • Les composants Talaxie : le dossier components du plugin org.talend.designer.components.localprovider, donné par RUXIE_COMPONENTS_DIR ou --components. Pour construire des routes, utilisez RUXIE_COMPONENTS_DIR : le serveur en déduit les composants Camel. The Talaxie components: the components folder of the org.talend.designer.components.localprovider plugin, given by RUXIE_COMPONENTS_DIR or --components. To build routes, use RUXIE_COMPONENTS_DIR: the server derives the Camel components from it.
  • Les bibliothèques des jobs : dans le dépôt Maven de l'utilisateur ou de l'installation Talaxie voisine du projet, sinon téléchargées. Le poste doit alors accéder à Internet. The job libraries: in the Maven repository of the user or of the Talaxie installation next to the project, otherwise downloaded. The machine then needs Internet access.

Options

Options de la ligne de commande, puis variables d'environnement. Command line options, then environment variables.

Option Description RequisRequired
--port <port> Port d'écoute.Listening port. OuiYes
--project <dossier> Projet à servir : un dossier qui contient talend.project. Répétable.Project to serve: a folder containing talend.project. Repeatable. L'un des deuxOne of them
--workspace <dossier> Sert tous les projets directement sous ce dossier, qui doit exister. Répétable. Un import crée les projets absents dans le premier workspace.Serves every project directly under this folder, which must exist. Repeatable. An import creates missing projects in the first workspace.
--host <adresse> Adresse d'écoute. Défaut : 127.0.0.1.Listening address. Default: 127.0.0.1. NonNo
--components <dossier> Dossier de composants, par priorité. Répétable. Remplace les dossiers par défaut.Component folder, by priority. Repeatable. Replaces the default folders. NonNo
--lang <fr|en> Langue des étapes de construction et du code généré. Défaut : celle du système.Language of the build steps and of the generated code. Default: the system language. NonNo
--help Affiche l'aide.Shows the help. NonNo
VariableVariable Description
RUXIE_SERVER_TOKEN Jeton d'accès. Sans cette variable, l'accès est libre et un avertissement s'affiche au démarrage.Access token. Without this variable, access is open and a warning is displayed at startup.
RUXIE_COMPONENTS_DIR Dossier des composants Talaxie.Talaxie components folder.
RUXIE_CODEGEN_DIR Dossier du générateur, s'il n'est pas à côté de l'exécutable.Generator folder, if it is not next to the executable.

SécuritéSecurity

Jeton d'accèsAccess token

Si RUXIE_SERVER_TOKEN est renseigné, chaque requête, sauf /health, doit porter cet en-tête. Sinon, le serveur répond 401. Sans cette variable, l'en-tête n'est pas nécessaire et tout programme qui atteint le port peut utiliser l'API. If RUXIE_SERVER_TOKEN is set, every request except /health must carry this header. Otherwise the server answers 401. Without this variable, the header is not needed and any program that reaches the port can use the API.

Authorization: Bearer <jeton>

Le jeton se donne uniquement par variable d'environnement : un argument serait visible dans la liste des processus. The token is only given through an environment variable: an argument would be visible in the process list.

Accès distantRemote access

Le serveur écoute par défaut sur la boucle locale et ne chiffre pas les échanges : le jeton et les archives circulent en clair. By default the server listens on the loopback address and does not encrypt traffic: the token and the archives travel in clear text.

warning Pour un accès distant, placez le serveur derrière un proxy HTTPS. Avec une autre adresse dans --host, il affiche un avertissement au démarrage. For remote access, put the server behind an HTTPS proxy. With another address in --host, it displays a warning at startup.
info Le détail d'un job n'expose pas ses paramètres, qui peuvent contenir des mots de passe. Le code généré et les archives peuvent en revanche en contenir sous forme chiffrée : traitez-les comme des données sensibles. Job details do not expose parameters, which can contain passwords. Generated code and archives can however contain them in encrypted form: treat them as sensitive data.
warning Le champ directory d'une construction fait écrire le serveur, avec les droits de son compte, dans le dossier choisi par le client, partages réseau compris. Le nom du fichier reste fixé par le serveur. Dès que d'autres programmes ou utilisateurs peuvent atteindre le port, renseignez RUXIE_SERVER_TOKEN et limitez les droits de ce compte. The directory field of a build makes the server write, with the rights of its account, to the folder chosen by the client, network shares included. The file name is still set by the server. As soon as other programs or users can reach the port, set RUXIE_SERVER_TOKEN and limit the rights of this account.
warning La route /import écrit dans les projets, crée ceux qui manquent dans le workspace et, avec overwrite=true, remplace des jobs sans retour possible. Le code Java de ces jobs se retrouve ensuite dans les archives construites. Sans RUXIE_SERVER_TOKEN, tout programme qui atteint le port peut le faire. The /import route writes to projects, creates missing ones in the workspace and, with overwrite=true, replaces jobs permanently. The Java code of these jobs then ends up in the built archives. Without RUXIE_SERVER_TOKEN, any program that reaches the port can do this.

Référence de l'APIAPI Reference

Toutes les routes commencent par /api/v1 et répondent en JSON, sauf le téléchargement d'une archive. Dans les URL, {projet} est le nom du dossier du projet, sans tenir compte de la casse, et {nom} le nom d'un job ou d'une route, sans sa version. All routes start with /api/v1 and answer in JSON, except archive downloads. In URLs, {projet} is the project folder name, ignoring case, and {nom} is the name of a job or route, without its version.

GET /health

État du serveur et version. Toujours sans jeton.Server state and version. Never needs a token.

{"status":"ok","version":"9.0.1"}
GET /projects

Projets servis.Served projects.

{"projects":[{"name":"CLIENT"},{"name":"DEMOESB"},{"name":"DEMOETL"}]}
GET /projects/{projet}/items

Jobs, Joblets et routes du projet. kind vaut job, joblet ou route, et folder donne le dossier dans la section.Jobs, Joblets and routes of the project. kind is job, joblet or route, and folder gives the folder within the section.

{"items":[
  {"kind":"job","name":"ESB01_000_JobESB_Master","version":"0.1","folder":"Talaxie"},
  {"kind":"route","name":"MaRouteTest","version":"0.2","folder":""}
]}
GET /projects/{projet}/jobs/{nom}?version=

Détail d'un job ou d'une route : versions, contextes, composants et liens. Sans version, la version listée par /items est utilisée. Les Joblets ne sont pas accessibles par cette route.Details of a job or route: versions, contexts, components and links. Without version, the version listed by /items is used. Joblets are not available through this route.

{
  "name": "ESB01_000_JobESB_Master",
  "kind": "job",
  "version": "0.1",
  "versions": ["0.1"],
  "purpose": "",
  "description": "",
  "status": "",
  "author": null,
  "created": "2026-08-21T15:15:42.946+0200",
  "modified": "2026-08-21T20:03:08.391+0200",
  "contexts": ["Default"],
  "defaultContext": "Default",
  "nodes": [
    {"name":"tRESTRequest_1","component":"tRESTRequest","label":null,"activated":true}
  ],
  "links": [
    {"name":"items","type":"FLOW","source":"tRESTRequest_1","target":"tExtractJSONFields_1"}
  ]
}
POST /projects/{projet}/jobs/{nom}/generate?version=

Génère le code Java et le renvoie dans la réponse, un fichier par classe. L'appel attend la fin de la génération.Generates the Java code and returns it in the response, one file per class. The call waits for the generation to finish.

{"files":[
  {"path":"client/impfou_000_master_0_5/IMPFOU_000_Master.java","content":"package client..."}
]}
POST /projects/{projet}/jobs/{nom}/builds

Met une construction en file et répond tout de suite 202. Le corps JSON est facultatif.Queues a build and immediately answers 202. The JSON body is optional.

ChampField Description DéfautDefault
type standalone (archive zip avec lanceurs), osgi (bundle pour un job ESB) ou kar (route).standalone (zip archive with launchers), osgi (bundle for an ESB job) or kar (route). Premier type proposé pour ce jobFirst type offered for this job
context Contexte des lanceurs.Launcher context. defaultContext
sources Joint les sources à un bundle ou à un .kar.Adds the sources to a bundle or a .kar. false
version Version à construire.Version to build. Version listée par /itemsVersion listed by /items
directory Dossier de l'archive sur le serveur, en chemin absolu. Il est créé s'il n'existe pas.Archive folder on the server, as an absolute path. It is created if it does not exist. Dossier temporaire du systèmeSystem temporary folder
updateMinor Avec true, monte la version mineure du job avant de le construire : la version de départ (version, sinon la plus récente) est copiée sous le numéro qui suit la version la plus récente du job, 0.3 donnant 0.4. Les versions existantes restent. La nouvelle version reste dans le projet même si la construction échoue.With true, raises the minor version of the job before building it: the starting version (version, otherwise the latest) is copied under the number following the latest version of the job, 0.3 giving 0.4. Existing versions stay. The new version stays in the project even if the build fails. false

L'archive se nomme {nom}_{version}.zip, {nom}-{version}.jar ou {nom}_{version}.kar selon le type. Dans directory, elle remplace un fichier de même nom et reste téléchargeable par /builds/{id}/archive. Si le serveur ne peut pas y écrire, la construction passe à failed. Dans le JSON, doublez les barres obliques inverses d'un chemin Windows :The archive is named {nom}_{version}.zip, {nom}-{version}.jar or {nom}_{version}.kar depending on the type. In directory, it replaces a file with the same name and can still be downloaded through /builds/{id}/archive. If the server cannot write there, the build becomes failed. In JSON, double the backslashes of a Windows path:

{"context":"Default","directory":"C:\\Talaxie\\builds"}

Réponse, avec dans version la version qui sera construite :Response, with in version the version that will be built:

{"id":"a4a4dfc78a4c59aed68b6ed24a2f3c6c","status":"queued","version":"0.4"}
GET /builds/{id}

Avancement d'une construction. status vaut queued, running, done ou failed. En cas d'échec, error donne la cause.Build progress. status is queued, running, done or failed. On failure, error gives the cause.

{
  "id": "a4a4dfc78a4c59aed68b6ed24a2f3c6c",
  "job": "MaRouteTest",
  "version": "0.4",
  "status": "done",
  "steps": ["Génération du code…","Recherche des bibliothèques…","Compilation…","Création de l'archive…"],
  "error": null
}
GET /builds/{id}/archive

Télécharge l'archive d'une construction terminée, avec son nom dans Content-Disposition. Tant que la construction n'est pas terminée avec succès, le serveur répond 409.Downloads the archive of a finished build, with its name in Content-Disposition. Until the build has succeeded, the server answers 409.

POST /projects/{projet}/import?overwrite=

Importe un job et ses dépendances, comme « Importer des éléments » dans Talaxie. Le corps de la requête est le fichier zip lui-même, avec l'en-tête Content-Type: application/zip : une archive d'export d'éléments, ou une archive de job qui contient ses éléments. Tous les éléments de l'archive sont importés dans leurs dossiers d'origine et sont visibles aussitôt.Imports a job and its dependencies, like "Import items" in Talaxie. The request body is the zip file itself, with the Content-Type: application/zip header: an item export archive, or a job archive that contains its items. All items of the archive are imported into their original folders and are visible immediately.

overwrite ComportementBehavior
absent ou falsemissing or false Rien n'est remplacé. Si un job ou une route de l'archive existent déjà, le serveur répond 409 et n'écrit rien. Un autre élément déjà présent (contexte, routine, métadonnée) reste tel quel et l'import continue.Nothing is replaced. If a job or route of the archive already exists, the server answers 409 and writes nothing. Any other item already present (context, routine, metadata) stays as it is and the import continues.
true Remplace les éléments de même nom, avec toutes leurs versions. Ce remplacement est définitif.Replaces items with the same name, along with all their versions. This replacement is permanent.

skipped liste les éléments non importés : ceux laissés en place, et ceux qui ne sont pas dans un dossier d'éléments du projet. L'archive est limitée à 64 Mo, 20 000 fichiers et 512 Mo une fois décompressée. Un import attend la fin de la construction en cours.skipped lists the items that were not imported: those left in place, and those outside the project item folders. The archive is limited to 64 MB, 20,000 files and 512 MB once decompressed. An import waits for the running build to finish.

Projet absent : si le serveur a un --workspace, l'import crée le projet dans le premier, avec ses routines système, de sorte que ses jobs se construisent aussitôt. Le dossier prend le nom en majuscules, donné par project dans la réponse, et created vaut true. Le nom commence par une lettre, suivie de lettres, de chiffres ou de _. Une archive refusée ne crée rien. Sans --workspace, le serveur répond 404.Missing project: if the server has a --workspace, the import creates the project in the first one, with its system routines, so its jobs can be built right away. The folder takes the uppercase name, given by project in the response, and created is true. The name starts with a letter, followed by letters, digits or _. A rejected archive creates nothing. Without --workspace, the server answers 404.

{
  "project": "CLIENT_TEST",
  "created": true,
  "imported": [
    {"path":"process/Job1/JOB01_000_JobEtl_Master_0.4","name":"JOB01_000_JobEtl_Master","version":"0.4"}
  ],
  "skipped": [
    {"path":"context/Default_0.1","name":"Default","version":"0.1"}
  ]
}

Codes de réponseStatus codes

Une erreur renvoie un objet JSON avec son message : An error returns a JSON object with its message:

{"error":"job inconnu : Rien"}
Code SignificationMeaning
200Succès.Success.
202Construction mise en file.Build queued.
400URL ou JSON invalide, type non proposé pour ce job, contexte inconnu, directory qui n'est pas un chemin absolu, nom invalide pour un projet à créer.Invalid URL or JSON, type not offered for this job, unknown context, directory that is not an absolute path, invalid name for a project to create.
401Jeton absent ou invalide.Missing or invalid token.
404Route, projet, job, version ou construction inconnus.Unknown route, project, job, version or build.
409Construction non terminée ou en échec. Lors d'un import : job déjà présent, ou dossier du workspace qui porte déjà le nom du projet à créer sans être un projet.Build not finished or failed. During an import: job already present, or a workspace folder that already has the name of the project to create without being a project.
413Corps de requête illisible ou supérieur à 64 Ko, ou à 64 Mo pour un import.Request body unreadable or larger than 64 KB, or 64 MB for an import.
415Import sans l'en-tête Content-Type: application/zip.Import without the Content-Type: application/zip header.
422Job illisible, génération en échec, ou archive à importer invalide, trop volumineuse ou sans élément.Unreadable job, generation failure, or import archive that is invalid, too large or without items.
429Trop de constructions en attente.Too many pending builds.
500Erreur du serveur, par exemple écriture impossible dans le projet. Un import peut alors rester partiel.Server error, for example when the project cannot be written to. An import can then remain partial.
info Les constructions passent une à la fois. Le serveur garde les 50 dernières dans le dossier temporaire du système, et ces fichiers restent après son arrêt. Il ne supprime jamais une archive écrite dans directory. L'historique des constructions, lui, repart de zéro à chaque démarrage. Builds run one at a time. The server keeps the last 50 in the system temporary folder, and these files remain after it stops. It never deletes an archive written to directory. The build history itself restarts from zero at each startup.

Exemples & AutomatisationExamples & Automation

Construire un job en PowerShellBuild a job in PowerShell

Lance la construction, attend sa fin, puis télécharge l'archive : Starts the build, waits for it to finish, then downloads the archive:

$base = "http://127.0.0.1:8787/api/v1"
$headers = @{ Authorization = "Bearer $env:RUXIE_SERVER_TOKEN" }

$build = Invoke-RestMethod -Method Post -Headers $headers `
  -Uri "$base/projects/CLIENT/jobs/IMPFOU_000_Master/builds" `
  -ContentType "application/json" -Body '{"context":"Default"}'

do {
  Start-Sleep -Seconds 2
  $state = Invoke-RestMethod -Headers $headers -Uri "$base/builds/$($build.id)"
} while ($state.status -in "queued", "running")

if ($state.status -eq "failed") { throw $state.error }

Invoke-WebRequest -Headers $headers -OutFile "IMPFOU_000_Master.zip" `
  -Uri "$base/builds/$($build.id)/archive"

Intégration dans un pipeline CI/CDCI/CD pipeline integration

Le même enchaînement en Bash, avec curl et jq : The same sequence in Bash, with curl and jq:

set -eo pipefail

BASE=http://127.0.0.1:8787/api/v1
AUTH="Authorization: Bearer $RUXIE_SERVER_TOKEN"

ID=$(curl -sf -X POST -H "$AUTH" -d '{"context":"Default"}' \
  "$BASE/projects/CLIENT/jobs/IMPFOU_000_Master/builds" | jq -r .id)

while true; do
  STATUS=$(curl -sf -H "$AUTH" "$BASE/builds/$ID" | jq -r .status)
  case "$STATUS" in
    done) break ;;
    failed) curl -s -H "$AUTH" "$BASE/builds/$ID" | jq -r .error; exit 1 ;;
  esac
  sleep 2
done

curl -sf -H "$AUTH" -OJ "$BASE/builds/$ID/archive"

Importer un jobImport a job

En PowerShell, puis en Bash avec curl, en reprenant les variables des exemples ci-dessus : In PowerShell, then in Bash with curl, reusing the variables of the examples above:

Invoke-RestMethod -Method Post -Headers $headers -ContentType "application/zip" `
  -InFile "IMPFOU_000_Master.zip" -Uri "$base/projects/CLIENT/import?overwrite=true"
curl -sf -X POST -H "$AUTH" -H "Content-Type: application/zip" \
  --data-binary @IMPFOU_000_Master.zip "$BASE/projects/CLIENT/import?overwrite=true"