Carte APIs Carte Server

Provides web service calls related to servers, such as allocating sockets and ports, getting the list of slaves and registering them, and displaying the initial Carte page.

Allocate server socket

get

Allocates port to use by client. Allows any client to ask for a port number to use. This is necessary several slaves can be run on the same host. The method ensures the port number is unique for host name provided and makes sure the slaves are using valid port numbers. Data communication across a cluster of Carte servers happens through TCP/IP sockets. Slave transformations sometimes open (or listen to) tens to hundreds of sockets. When you want to allocate the port numbers for data communication between slave transformation in a kettle clustering run, you need unique combinations of all the parameters below.

Example Request:

GET /kettle/allocateSocket/?xml=Y&rangeStart=100&host=locahost&id=clust&trans=my_trans&sourceSlave=slave_1&sourceStep=200&sourceCopy=1&targetSlave=slave_2&targetStep=50&targetCopy=1

Authorizations

AuthorizationstringRequired

HTTP Basic Authentication

Query parameters

xmlstring · enumOptional

Return XML format when Y, HTML otherwise

Default: NPossible values:

rangeStartintegerOptional

Port number to start looking from

hoststringOptional

Port's host

idstringOptional

Carte container id

transstringOptional

Running transformation id

sourceSlavestringOptional

Name of the source slave server

sourceStepintegerOptional

Port number step used on source slave server

sourceCopyintegerOptional

Number of copies of the step on source server

targetSlavestringOptional

Name of the target slave server

targetStepintegerOptional

Port number step used on target slave server

targetCopyintegerOptional

Number of copies of the step on target server

Responses

200

Socket allocated successfully

text/xml

Responsestring

Socket allocation result

500

Internal server error

text/xml

get

/kettle/allocateSocket

GET /kettle/allocateSocket HTTP/1.1
Host: 
Authorization: Basic username:password
Accept: */*

<?xml version="1.0" encoding="UTF-8"?>
<port>100</port>

List allocated server sockets

get

Gets list of ports for specified host. Method is used for listing all or just open ports for specified host. Response contains port number, which transformation it is (was) used for, current status of the port and last date time used.

Example Request:

GET /kettle/listSocket/?host=127.0.0.1

Authorizations

AuthorizationstringRequired

HTTP Basic Authentication

Query parameters

hoststringRequired

Host to get ports for

Example: 127.0.0.1

onlyOpenstring · enumOptional

Boolean flag that indicates whether all or only open ports should be returned. Set it to Y to get the list of only currently open ports.

Possible values:

Responses

200

Socket list retrieved successfully

text/html

Responsestring

HTML document listing the ports requested

500

Internal server error

text/xml

get

/kettle/listSocket

GET /kettle/listSocket?host=text HTTP/1.1
Host: 
Authorization: Basic username:password
Accept: */*

<HTML>
<HEAD><TITLE>List of server sockets on server '127.0.0.1'</TITLE></HEAD>
<BODY>
<H1>Ports for host '127.0.0.1'</H1>
Found 5 ports for host '127.0.0.1'<p>
8088 : Transformation=dummy-trans, crt/Dummy (do nothing) 2.0
--> sll/Dummy (do nothing).0
id=b20bcd03-9682-4327-8c42-b129faabbfe1, allocated=false
time=Mon Nov 17 09:31:15 BRT 2014
<br>
8089 : Transformation=dummy-trans, crt/Dummy (do nothing) 2.0
--> sll/Dummy (do nothing).1
id=b20bcd03-9682-4327-8c42-b129faabbfe1, allocated=false
time=Mon Nov 17 09:31:15 BRT 2014
<br>
8090 : Transformation=dummy-trans, crt/Dummy (do nothing) 2.0
--> sll/Dummy (do nothing).2
id=b20bcd03-9682-4327-8c42-b129faabbfe1, allocated=false
time=Mon Nov 17 09:31:15 BRT 2014
<br>
8091 : Transformation=dummy-trans, crt/Dummy (do nothing) 2.0
--> sll/Dummy (do nothing).3
id=b20bcd03-9682-4327-8c42-b129faabbfe1, allocated=false
time=Mon Nov 17 09:31:15 BRT 2014
<br>
8092 : Transformation=dummy-trans, crt/Dummy (do nothing) 2.0
--> sll/Dummy (do nothing).4
id=b20bcd03-9682-4327-8c42-b129faabbfe1, allocated=false
time=Mon Nov 17 09:31:15 BRT 2014
<br>
</BODY>
</HTML>

Get next sequence value

get

Increments specified pre-configured sequence. Method is used for reserving a number of IDs and incrementing a sequence pre-configured in Carte server configuration by specified amount. If no increment value provided 10000 is used by default.

Example Request:

GET /kettle/nextSequence?name=test_seq

Authorizations

AuthorizationstringRequired

HTTP Basic Authentication

Query parameters

namestringRequired

Name of the sequence specified in Carte configuration file

Example: test_seq

incrementintegerOptional

Parameter used for incrementing sequence. If no parameter specified 10000 is used by default.

Default: 10000

Responses

200

Next sequence value retrieved

text/xml

Responsestring

XML containing sequence value and the increment value used

500

Internal server error

text/xml

get

/kettle/nextSequence

GET /kettle/nextSequence?name=text HTTP/1.1
Host: 
Authorization: Basic username:password
Accept: */*

<seq><value>570000</value><increment>10000</increment></seq>

Register slave server

post

Registers slave server in the master. The method is used to add or update information of slave server.

Example Request:

POST /kettle/registerSlave/

Request body should contain xml containing slave server description.

Authorizations

AuthorizationstringRequired

HTTP Basic Authentication

Body

stringOptional

SlaveServerDetection XML

Responses

200

Slave server registered successfully

text/xml

500

Internal server error

text/xml

post

/kettle/registerSlave

POST /kettle/registerSlave HTTP/1.1
Host: 
Authorization: Basic username:password
Content-Type: application/xml
Accept: */*
Content-Length: 6

"text"

<?xml version="1.0" encoding="UTF-8"?>
<webresult>
  <result>OK</result>
  <message>Slave server detection 'Dynamic slave [localhost:901]' was replaced in the list.</message>
  <id/>
</webresult>

Get registered slave servers

get

Gets list of slave servers. Retrieves list of slave servers which are known to specific server.

Example Request:

GET /kettle/getSlaves

Authorizations

AuthorizationstringRequired

HTTP Basic Authentication

Query parameters

xmlstring · enumOptional

Return XML format when Y, HTML otherwise

Default: NPossible values:

Responses

200

Slave servers list retrieved successfully

text/xml

Responsestring

List of registered slave servers

500

Internal server error

text/xml

get

/kettle/getSlaves

GET /kettle/getSlaves HTTP/1.1
Host: 
Authorization: Basic username:password
Accept: */*

<?xml version="1.0" encoding="UTF-8"?>
<SlaveServerDetections>
  <SlaveServerDetection>
    <slaveserver>
      <name>Dynamic slave [localhost:909]</name>
      <hostname>localhost</hostname>
      <port>909</port>
      <webAppName/>
      <username>cluster</username>
      <password>Encrypted 2be98afc86aa7f2e4cb1aa265cd86aac8</password>
      <proxy_hostname/>
      <proxy_port/>
      <non_proxy_hosts/>
      <master>N</master>
    </slaveserver>
    <active>Y</active>
    <last_active_date>2014/11/17 06:42:28.043</last_active_date>
    <last_inactive_date>2014/11/17 06:42:27.372</last_inactive_date>
  </SlaveServerDetection>
</SlaveServerDetections>

Get server status

get

Retrieve server status. The status contains information about the server itself (OS, memory, etc) and information about jobs and transformations present on the server.

Example Request:

GET /kettle/status/?xml=Y

Authorizations

AuthorizationstringRequired

HTTP Basic Authentication

Query parameters

xmlstring · enumOptional

Return XML format when Y, HTML otherwise

Default: NPossible values:

Responses

200

Server status retrieved successfully

text/xml

Responsestring

Server status in XML format including memory, CPU, OS info and running transformations/jobs

500

Internal server error

text/xml

get

/kettle/status

GET /kettle/status HTTP/1.1
Host: 
Authorization: Basic username:password
Accept: */*

<?xml version="1.0" encoding="UTF-8"?>
<serverstatus>
  <statusdesc>Online</statusdesc>
  <memory_free>229093440</memory_free>
  <memory_total>285736960</memory_total>
  <cpu_cores>4</cpu_cores>
  <cpu_process_time>7534848300</cpu_process_time>
  <uptime>68818403</uptime>
  <thread_count>45</thread_count>
  <load_avg>-1.0</load_avg>
  <os_name>Windows 7</os_name>
  <os_version>6.1</os_version>
  <os_arch>amd64</os_arch>
  <transstatuslist>
    <transstatus>
      <transname>dummy-trans</transname>
      <id>c56961b2-c848-49b8-abde-76c8015e29b0</id>
      <status_desc>Stopped</status_desc>
      <error_desc/>
      <paused>N</paused>
      <stepstatuslist>
      </stepstatuslist>
      <first_log_line_nr>0</first_log_line_nr>
      <last_log_line_nr>0</last_log_line_nr>
    </transstatus>
  </transstatuslist>
  <jobstatuslist>
  </jobstatuslist>
</serverstatus>

Shutdown Carte server

get

Stops the Carte server. This method must be set up initially through the CLI and is used for stopping the Carte server.

Example Request:

GET http://localhost:8080/pentaho/kettle/stopCarte

Authorizations

AuthorizationstringRequired

HTTP Basic Authentication

Query parameters

xmlstring · enumOptional

Return XML format when Y, HTML otherwise

Default: NPossible values:

Responses

200

Request was processed

500

Internal server error occurs during request processing

text/xml

get

/kettle/stopCarte

GET /kettle/stopCarte HTTP/1.1
Host: 
Authorization: Basic username:password
Accept: */*

<?xml version="1.0" encoding="UTF-8"?>
<request_accepted>true</request_accepted>

PreviousStatus Responses NextCarte APIs Transformations