Home \| Table of Contents	Simple HTTP API
Prev		Next

Chapter 12. Simple HTTP API

This API is intended for all HTTP clients (even for the simplest ones - like wget tool). All operations are accessible using http GET method and return plain text. Thus response can be parsed by simple tools. If global security is on (default setting), BASIC HTTP authentication is required. Use CloverETL Server user with proper permissions.

URL has this pattern:

http://[domain]:[port]/[context]/[servlet]/[operation]?[param1]=[value1]&[param2]=[value2]...

Operation help

parameters

returns

list of possible operations and parameters

example

http://localhost:8080/clover/request_processor/help

Operation graph_run

parameters

Table 12.1. Parameters of graph_run

parameter name	mandatory	default	description
graphID	yes	-	Text Id, which is unique in specified sandbox. May be file path relative to sandbox root
sandbox	yes	-	Text ID of sandbox
runtime config	no	default	Text ID of runtime config for this execution. If not specified, default will be used.
additional graph parameters	no		Any URL parameter with "param_" prefix is passed to executed graph and may be used in graph XML as placeholder, but without "param_" prefix. i.e. "param_file_name" specified in URL may be used in the graph as ${file_name}. These parameters are resolved only during loading of graph XML, so graph cannot be pooled.

returns

run ID: incremental number, which identifies each execution request

example

http://localhost:8080/clover/request_processor/graph_run?graphID=graphDBExecute&sandbox=mva

Operation graph_status

parameters

Table 12.2. Parameters of graph_status

parameter name	mandatory	default	description
runID	yes	-	Id of each graph execution
returnType	no	STATUS	STATUS \| STATUS_TEXT \| DESCRIPTION \| DESCRIPTION_XML
waitForStatus	no	-	Status code which we want to wait for. If it is specified, this operation will wait until graph is in required status.
waitTimeout	no	0	If waitForStatus is specified, it will wait only specified amount of milliseconds. Default 0 means forever, but it depends on application server configuration. When the specified timeout expires and graph run still isn't in required status, server returns code 408 (Request Timeout). 408 code may be also returned by application server if its HTTP request timeout expires before.

returns

Status of specified graph. It may be number code, text code or complex description in dependence of optional parameter returnType. Description is returned as plain text with pipe as separator, or as XML. Schema describing XML format of the XML response is accessible on CloverETL Server URL: http://[host]:[port]/clover/schemas/executions.xsd In dependence on waitForStatus parameter may return result immediately or wait for specified status.

example

http://localhost:8080/clover/request_processor/graph_status?runID=123456&returnType=DESCRIPTION&waitForStatus=FINISHED&waitTimeout=60000

Operation graph_kill

parameters

Table 12.3. Parameters of graph_kill

parameter name	mandatory	default	description
runID	yes	-	Id of each graph execution
returnType	no	STATUS	STATUS \| STATUS_TEXT \| DESCRIPTION

returns

Status of specified graph after attempt to kill it. It may be number code, text code or complex description in dependence of optional parameter.

example

http://localhost:8080/clover/request_processor/graph_kill?runID=123456&returnType=DESCRIPTION

Operation server_jobs

parameters

returns

List of runID which are currently running.

example

http://localhost:8080/clover/request_processor/server_jobs

Operation sandbox_list

parameters

returns

List of all sandbox text IDs. In next versions will return only accessible ones.

example

http://localhost:8080/clover/request_processor/sandbox_list

Operation sandbox_content

parameters

Table 12.4. Parameters of sandbox_content

parameter name	mandatory	default	description
sandbox	yes	-	text ID of sandbox

returns

List of all elements in specified sandbox. Each element may be specified as file path relative to sandbox root.

example

http://localhost:8080/clover/request_processor/sandbox_content?sandbox=mva

Operation executions_history

parameters

Table 12.5. Parameters of executions_history

parameter name	mandatory	default	description
sandbox	yes	-	text ID of sandbox
from	no		Lower datetime limit. Operation will return only records after(and equal) this datetime. Format: "yyyy-MM-dd HH:mm" (must be URL encoded)
to	no		Lower datetime limit. Operation will return only records after(and equal) this datetime. Format: "yyyy-MM-dd HH:mm" (must be URL encoded) status
status	no		Current execution status. Operation will return only records with specified STATUS. Meaningful values are RUNNING \| ABORTED \| FINISHED_OK \| ERROR
sandbox	no		Sandbox code. Operation will return only records for graphs from specified sandbox.
graphId	no		Text Id, which is unique in specified sandbox. File path relative to sandbox root
orderBy	no		Attribute for list ordering. Possible values: id \| graphId \| finalStatus \| startTime \| stopTime. There is no ordering by default.
orderDescend	no	true	Switch which specifies ascending or descending ordering. If it is true (which is default), ordering is descending.
returnType	no	IDs	Possible values are: IDs \| DESCRIPTION \| DESCRIPTION_XML
index	no	0	Index of the first returned records in whole record set. (starting from
records	no	infinite	Max amount of returned records.

returns

List of executions according to filter criteria.

For returnType==IDs returns simple list of runIDs (with new line delimiter).

For returnType==DESCRIPTION returns complex response which describes current status of selected executions, their phases, nodes and ports.

execution|[runID]|[status]|[username]|[sandbox]|[graphID]|[startedDatetime]|[finishedDatetime]|[clusterNode]|[graphVersion]
phase|[index]|[execTimeInMilis]
node|[nodeID]|[status]|[totalCpuTime]|[totalUserTime]|[cpuUsage]|[peakCpuUsage]|[userUsage]|[peakUserUsage]
port|[portType]|[index]|[avgBytes]|[avgRows]|[peakBytes]|[peakRows]|[totalBytes]|[totalRows]

example of request

http://localhost:8080/clover/request_processor/executions_history?from=&to=2008-09-16+16%3A40&status=&sandbox=def&graphID=&index=&records=&returnType=DESCRIPTION

example of DESCRIPTION (plain text) response

execution|13108|FINISHED_OK|clover|def|test.grf|2008-09-16 11:11:19|2008-09-16 11:11:58|nodeA|2.4
phase|0|38733
node|DATA_GENERATOR1|FINISHED_OK|0|0|0.0|0.0|0.0|0.0
port|Output|0|0|0|0|0|130|10
node|TRASH0|FINISHED_OK|0|0|0.0|0.0|0.0|0.0
port|Input|0|0|0|5|0|130|10
node|SPEED_LIMITER0|FINISHED_OK|0|0|0.0|0.0|0.0|0.0
port|Input|0|0|0|0|0|130|10
port|Output|0|0|0|5|0|130|10
execution|13107|ABORTED|clover|def|test.grf|2008-09-16 11:11:19|2008-09-16 11:11:30
phase|0|11133
node|DATA_GENERATOR1|FINISHED_OK|0|0|0.0|0.0|0.0|0.0
port|Output|0|0|0|0|0|130|10
node|TRASH0|RUNNING|0|0|0.0|0.0|0.0|0.0
port|Input|0|5|0|5|0|52|4
node|SPEED_LIMITER0|RUNNING|0|0|0.0|0.0|0.0|0.0
port|Input|0|0|0|0|0|130|10
port|Output|0|5|0|5|0|52|4

For returnType==DESCRIPTION_XML returns complex data structure describing one or more selected executions in XML format. Schema describing XML format of the XML response is accessible on CloverETL Server URL: http://[host]:[port]/clover/schemas/executions.xsd

Operation suspend

Suspends server or sandbox(if specified). Suspension means, that no graphs may me executed on suspended server/sandbox.

parameters

Table 12.6. Parameters of suspend

parameter name	mandatory	default	description
sandbox	no	-	Text ID of sandbox to suspend. If not specified, it suspends whole server.
atonce	no		If this param is set to true, running graphs from suspended server(or just from sandbox) are aborted. Otherwise it can run until it is finished in common way.

returns

Result message

Operation resume

parameters

Table 12.7. Parameters of resume

parameter name	mandatory	default	description
sandbox	no	-	Text Id of sandbox to resume. If not specified, server will be resumed.

returns

Result message

Prev		Next
WebDAV authentication/authorization	Home \| Table of Contents	JMX mBean