Workflow REST API

 End-Points

The API is composed by the following end-points:

• /workflows
• /jobs
• /jobs/:uuid/info

/workflows accept any of the HTTP verbs for the usual CRUD but /jobs will not accept PUT, given the only way to modify a Job once it has been created is through execution.

For the same reason, /jobs/:uuid/info will not accept neither POST requests, since the staus information for a Job is created when the Job itself is created, neither DELETE, given the status information for a job will be removed only if the job is removed.

GET /workflows

Retrieve a list of all the existing workflows.

HTTP Parameters.

None.

Status Codes

• 200 OK: A list of existing workflows is returned, even if there isn't any workflow, which will result on an empty array.

 Response Body

An array of workflow objects, (see POST /workflows).

POST /workflows

Create a new workflow.

HTTP Parameters

• name: The workflow name. Required.
• chain[]: The tasks to add to the workflow. Optional. Multiple values allowed.
• onerror[]: The tasks to add to the workflow fallback. Optional. Multiple values allowed.
• timeout: Optional timeout, in seconds, for the workflow execution.

Every task may be composed of:

• name: The task name. Optional.
• body: Required. A string enclosing a JavaScript function definition. The function must take the parameters job and cb, where cb is a callback to be called by the function when its execution is finished, either without any arguments, (task succeed), or with an error message, (task failed).
• fallback: Optional. A string enclosing a JavaScript function definition. The function must take the parameters err, job and cb, where cb is a callback to be called by the function when its execution fails; err is the error message returned by task body.
• retry: Optional. Number of times to retry the task's body execution before either fail the task or call the fallback function, when given.
• timeout: Optional timeout, in seconds, for the task execution.

Status Codes

• 409 Conflict: One of the required parameters is either missing or incorrect Information about the missing/incorrect parameter will be included into response body.
• 201 Created: Successful creation of the workflow. The workflow's JSON representation will be included into the response body, together with a Location header for the new resource. Generated workflow's uuid will be part of this Location and a member of the returned workflow JSON object.

 Response Body:

{
  uuid: UUID,
  name: 'The workflow name',
  chain: [:task, :task, ...],
  onerror: [:task, :task, ...],
  timeout: 3600(secs)
}

Sample task on the response:

{
  uuid: UUID,
  name: 'The task name',
  body: "function(job, cb) {
    if (job.foo) {
      return cb(null);
    } else {
      return cb('Uh, oh!, no foo.');
    }
  }",
  fallback: "function(err, job, cb) {
    if (err === 'Uh, oh!, no foo.') {
      job.foo = 'bar';
      return cb(null);
    } else {
      return cb('Arise chicken, arise!');
    }
  }",
  timeout: 360(secs)
}

GET /workflows/:wf_uuid

 HTTP Parameters:

• wf_uuid: The workflow UUID.

Status Codes:

• 404 Not Found: There's no worlflow with the provided wf_uuid.
• 200 OK: The workflow with the provided wf_uuid has been found and is returned as response body.

Note this API will not keep track of destroyed workflows, therefore, when a request for such workflows is made, the HTTP Status code will be 404 Not Found instead of 410 Gone.

Response body

Same than for POST /workflows + wf_uuid.

PUT /workflows/:wf_uuid

HTTP Parameters

Same than for POST /workflows.

 Status Codes

Same than for POST /workflows with the addition of:

• 404 Not Found, when the provided wf_uuid cannot be found on the backend.

 Response body

Same than for POST /workflows.

DELETE /workflows/:wf_uuid

 HTTP Parameters:

• wf_uuid: The workflow UUID.

Status Codes

• 204 OK: Workflow successfully destroyed.

GET /jobs

Retrieve a list of jobs. Without execution HTTP parameter all the existing jobs will be retrieved. If execution is given, only the jobs on the given execution status are retrieved.

HTTP Parameters.

• execution: Optional, one of suceeded, failed, running or queued.

Status Codes

• 200 OK: A list of existing jobs is returned, even when it's totally empty.

POST /jobs

HTTP Parameters.

• workflow: Required. UUID of the workflow from which the new job will be created.
• exec_after: Optional, ISO 8601 Date. Delay job execution until the provided time.
• target: The job's target, intended to restrict the creation of another job with this same target and same extra parameters while this one execution hasn't finished.
• Any extra k/v pairs of parameters desired, which will be passed to the job object as an object like {k1: v1, k2: v2, ...}.

Status Codes

• 409 Conflict: One of the required parameters is either missing or incorrect Information about the missing/incorrect parameter will be included into response body.
• 201 Created: Successful creation of the job. The job's JSON representation will be included into the response body, together with a Location header for the new resource. Generated job's uuid will be part of this Location and a member of the returned job JSON object.

 Response Body

{
  uuid: UUID,
  workflow_uuid: wf_uuid,
  name: 'The workflow name',
  chain: ['task object', 'task object', ...],
  onerror: ['task object', 'task object', ...],
  timeout: 3600,
  exec_after: new Date().toISOString(),
  target: '/some/uri',
  params: {
    k1: v1,
    k2: v2
  },
  chain_results: [{result: 'OK', error: ''}, ...],
  onerror_results: [{result: 'OK', error: ''}, ...],
  execution: 'queued' ('running'|'failure'|'success')
}

GET /jobs/:job_uuid

HTTP Parameters.

• job_uuid: The job's UUID.

Status Codes

• 404 Not Found: There's no job with the provided job_uuid.
• 200 OK: The task with the provided job_uuid has been found and is returned as response body.

Note this API will not keep track of destroyed jobs, therefore, when a request for such tasks is made, the HTTP Status code will be 404 Not Found instead of 410 Gone.

 Response Body

Same than for POST /jobs.

PUT /jobs/:job_uuid

TBD. Response with status code 405 Method Not Allowed.

DELETE /jobs/:job_uuid

TBD. Response with status code 405 Method Not Allowed.

POST /jobs/:job_uuid/cancel

Cancel a job's execution. The job should not be finished in order to be cancelable.

HTTP Parameters.

• job_uuid: The job's UUID.

Status Codes

• 404 Not Found: There's no job with the provided job_uuid.
• 409 Conflict: The job is already finalized and cannot be canceled.
• 200 OK: Successfully canceled job.

 Response Body

Same than for POST /jobs.

GET /jobs/:job_uuid/info

Detailed information for the given job. A task may result into a 3rd party application executing a process which may require some time/steps to finish. While our task is running and waiting for the finalization of such process, those 3rd party applications can publish information about progress using POST /jobs/:job_uuid/info; this information could then being used by other applications interested on job results using GET /jobs/:job_uuid/info.

This information will consist into an arbitrary length array, where every POST request will result in a new member being appended.

HTTP Parameters.

• job_uuid: The job's UUID.

Status Codes

Same than for GET /jobs/:job_uuid.

 Response Body

[
  { '10%': 'Task completed step one' },
  { '20%': 'Task completed step two' }
]

POST /jobs/:job_uuid/info

HTTP Parameters.

• message: Required. Object containing a message regarding operations progresses.

  { '10%': 'Task completed step one' }

Note you can provide any key/value pair here.

Status Codes

Same than for GET /jobs/:job_uuid.

 Response Body

None.

PUT /jobs/:job_uuid/info

Response with status code 405 Method Not Allowed.

DELETE /jobs/:job_uuid/info

Response with status code 405 Method Not Allowed.