|
<< Click to Display Table of Contents >> Navigation: Robo-FTP User's Guide > Robo-FTP Framework > Advanced > REST API |
The Robo-FTP Enterprise Framework offers a powerful REST API that allows you to interact directly with the Framework to perform tasks like create new jobs, edit jobs, run jobs, and perform various queries against Framework objects.
Below, ENDPOINT refers to the protocol, host, and port which the Framework is currently running under. Example ENDPOINT: http://localhost:59121
Unless otherwise noted, a successful API request returns a standard HTTP 200 ("OK") response. A failed request similarly returns a standard HTTP error code denoting the nature of the request (e.g. 404 "not found", 403 "permission denied", 400 "bad request", etc.)
The supported authentication method is NTLM.
INTERACTING WITH JOBS
List Jobs by Group:
GET ENDPOINT/api/job/listbygroup/JOBGROUP
Request Body: (none)
Response Body: json document containing a list of strings, each corresponding to a job name under specified group JOBGROUP
Get Job History:
GET ENDPOINT/api/job/history/JOBGROUP.JOBNAME
Request Body: (none)
Response Body: json document containing a list of integers, corresponding to all runIds for the specified job
Get Job Status
GET ENDPOINT/api/job/status/JOBGROUP.JOBNAME
Request Body: (none)
Response Body: json document containing the following properties and associated values:
name: (the job name)
group: (the job group)
lastTime: (last time the job was run)
lastRun: (run id of the previous job run, or null if never run)
lastResult: (run result code of the most recent job run, or null if never run)
currentRun: (run id of currently active run, or null if not currently active)
Disable Job Schedule
POST ENDPOINT/api/job/disable/JOBGROUP.JOBNAME
Request Body: (none)
Response Body: (none)
Enable Job Schedule
POST ENDPOINT/api/job/enable/JOBGROUP.JOBNAME
Request Body: (none)
Response Body: (none)
Get Job Configuration
GET ENDPOINT/api/job/config/JOBGROUP.JOBNAME
Request Body: (none)
Response Body: json document describing a job configuration (see "Job Configuration Grammar" below)
Change Job Configuration
PUT ENDPOINT/api/job/config/JOBGROUP.JOBNAME
Request Body: json document describing a job configuration (see "Job Configuration Grammar" below)
Response Body: (none)
Delete Job
POST ENDPOINT/api/job/delete/JOBGROUP.JOBNAME
Request Body: (none)
Response Body: (none)
Create New Job
POST ENDPOINT/api/job/create/JOBGROUP.JOBNAME
Request Body: (same as in "Change Job Configuration")
Response Body: (none)
Additional Notes: Here JOBNAME will be the name of the newly created job. The group JOBGROUP must already exist.
Start Job
POST ENDPOINT/api/job/start/JOBGROUP.JOBNAME
Request Body: (none)
Response Body: a single integer indicating the runId of the newly started job run
INTERACTING WITH RUNS
Stop Run
POST ENDPOINT/api/run/stop/RUNID
Request Body: (none)
Response Body: (none) on success, string indicating relevant error message on failure
Get Run Status
GET ENDPOINT/api/run/status/RUNID
Request Body: (none)
Response Body: json document consisting of an object containing properties about a job run, as follows:
name: name of the associated job
group: name of the associated job group
started: time when the job was started
ended: time when the job completed (or null if still running)
result: Robo-FTP error code for the result of this job run (-1 if job is still running)
last_message: Most recent message outputted by this job run
Get Run Steps
GET ENDPOINT/api/run/steps/RUNID
Request Body: (none)
Response Body: json document consisting of a list of stepData objects. Each such object describes information about each file processed during this job run, and contains the following properties:
name: the step name
stamp: timestamp when the relevant file was processed by this step
details: additional information relevant to the processing of this file during this step
result: Robo-FTP error code for the result of processing this file during this step (0 indicates success)
source_file: incoming filename at the beginning of this step
target_file: outgoing filename at the end of this step
JOB CONFIGURATION GRAMMAR
Requests like /api/job/create/ and /api/job/config should be made with a "jobConfiguration" body as part of the request:
jobConfiguration: [ stepConfiguration, ... ]
stepConfiguration: { stepInstanceName: stepNameValPairs }
stepInstanceName: a json string of form "STEPNAME_jobStepN". Here STEPNAME is a built-in or custom step such as "monitor" or "deliver", and N marks this as the Nth step (starting from 0). Example: "monitor_jobStep0"
stepNameValPairs: { iniVariable: iniValue, ... }
iniVariable: a json string describing the name of an INI variable associated with this step type. See the documentation for each Framework step for a list of these variables and their expected values where relevant.
iniValue: a json string to be assigned to the corresponding iniVariable
Example Job Configuration:
[
{
"monitor_jobStep0": {
"path": "C:\\data\\outgoing",
"report_on_error": "true",
"skip_email_on_error": "false",
"continue_on_error": "false",
"error1164_report_on_error": "true",
"error1164_skip_email_on_error": "false",
"error1164_continue_on_error": "false"
}
},
{
"deliver_jobStep1": {
"path": "C:\\data\\outgoing\\archive",
"report_on_error": "true",
"skip_email_on_error": "false",
"continue_on_error": "false",
"error1164_report_on_error": "true",
"error1164_skip_email_on_error": "false",
"error1164_continue_on_error": "false"
}
}
]