API

Overview

You can communicate with Dkron using a RESTful JSON API over HTTP. Dkron nodes usually listen on port 8080 for API requests. All examples in this section assume that you’ve found a running leader at localhost:8080.

Dkron implements a RESTful JSON API over HTTP to communicate with software clients. Dkron listens in port 8080 by default. All examples in this section assume that you’re using the default port.

Default API responses are unformatted JSON add the pretty=true param to format the response.

Version information

Version : 0.9.4

URI scheme

Host : localhost:8080
BasePath : /v1
Schemes : HTTP

Consumes

  • application/json

Produces

  • application/json

Paths

GET /

Description

Gets Status object.

Responses

HTTP Code Description Schema
200 Successful response status

Tags

  • default

Example HTTP request

Request path
/

Example HTTP response

Response 200
json :
"{ }"

GET /executions/{job_name}

Description

List executions.

Parameters

Type Name Description Schema
Path job_name
required
The job that owns the executions to be fetched. string

Responses

HTTP Code Description Schema
200 Successful response < execution > array

Tags

  • executions

Example HTTP request

Request path
/executions/string

Example HTTP response

Response 200
json :
"array"

GET /jobs

Description

List jobs.

Responses

HTTP Code Description Schema
200 Successful response < job > array

Tags

  • jobs

Example HTTP request

Request path
/jobs

Example HTTP response

Response 200
json :
"array"

POST /jobs

Description

Create or updates a new job.

Parameters

Type Name Description Schema
Body body
required
Updated job object job

Responses

HTTP Code Description Schema
201 Successful response job

Tags

  • jobs

Example HTTP request

Request path
/jobs
Request body
json :
{
  "name" : "string",
  "schedule" : "string",
  "command" : "string",
  "shell" : true,
  "owner" : "string",
  "owner_email" : "string",
  "success_count" : 0,
  "error_count" : 0,
  "last_success" : "string",
  "last_error" : "string",
  "disabled" : true,
  "tags" : {
    "string" : "string"
  },
  "retries" : 2,
  "parent_job" : "parent_job",
  "dependent_jobs" : [ "string" ],
  "processors" : {
    "string" : "string"
  },
  "concurrency" : "allow"
}

Example HTTP response

Response 201
json :
{
  "name" : "string",
  "schedule" : "string",
  "command" : "string",
  "shell" : true,
  "owner" : "string",
  "owner_email" : "string",
  "success_count" : 0,
  "error_count" : 0,
  "last_success" : "string",
  "last_error" : "string",
  "disabled" : true,
  "tags" : {
    "string" : "string"
  },
  "retries" : 2,
  "parent_job" : "parent_job",
  "dependent_jobs" : [ "string" ],
  "processors" : {
    "string" : "string"
  },
  "concurrency" : "allow"
}

GET /jobs/{job_name}

Description

Show a job.

Parameters

Type Name Description Schema
Path job_name
required
The job that needs to be fetched. string

Responses

HTTP Code Description Schema
200 Successful response job

Tags

  • jobs

Example HTTP request

Request path
/jobs/string

Example HTTP response

Response 200
json :
{
  "name" : "string",
  "schedule" : "string",
  "command" : "string",
  "shell" : true,
  "owner" : "string",
  "owner_email" : "string",
  "success_count" : 0,
  "error_count" : 0,
  "last_success" : "string",
  "last_error" : "string",
  "disabled" : true,
  "tags" : {
    "string" : "string"
  },
  "retries" : 2,
  "parent_job" : "parent_job",
  "dependent_jobs" : [ "string" ],
  "processors" : {
    "string" : "string"
  },
  "concurrency" : "allow"
}

POST /jobs/{job_name}

Description

Executes a job.

Parameters

Type Name Description Schema
Path job_name
required
The job that needs to be run. string

Responses

HTTP Code Description Schema
202 Successful response job

Tags

  • jobs

Example HTTP request

Request path
/jobs/string

Example HTTP response

Response 202
json :
{
  "name" : "string",
  "schedule" : "string",
  "command" : "string",
  "shell" : true,
  "owner" : "string",
  "owner_email" : "string",
  "success_count" : 0,
  "error_count" : 0,
  "last_success" : "string",
  "last_error" : "string",
  "disabled" : true,
  "tags" : {
    "string" : "string"
  },
  "retries" : 2,
  "parent_job" : "parent_job",
  "dependent_jobs" : [ "string" ],
  "processors" : {
    "string" : "string"
  },
  "concurrency" : "allow"
}

DELETE /jobs/{job_name}

Description

Delete a job.

Parameters

Type Name Description Schema
Path job_name
required
The job that needs to be deleted. string

Responses

HTTP Code Description Schema
200 Successful response job

Tags

  • jobs

Example HTTP request

Request path
/jobs/string

Example HTTP response

Response 200
json :
{
  "name" : "string",
  "schedule" : "string",
  "command" : "string",
  "shell" : true,
  "owner" : "string",
  "owner_email" : "string",
  "success_count" : 0,
  "error_count" : 0,
  "last_success" : "string",
  "last_error" : "string",
  "disabled" : true,
  "tags" : {
    "string" : "string"
  },
  "retries" : 2,
  "parent_job" : "parent_job",
  "dependent_jobs" : [ "string" ],
  "processors" : {
    "string" : "string"
  },
  "concurrency" : "allow"
}

GET /leader

Description

List leader of cluster.

Responses

HTTP Code Description Schema
200 Successful response member

Tags

  • default

Example HTTP request

Request path
/leader

Example HTTP response

Response 200
json :
{
  "Name" : "string",
  "Addr" : "string",
  "Port" : 0,
  "Tags" : {
    "string" : "string"
  },
  "Status" : 0,
  "ProtocolMin" : 0,
  "ProtocolMax" : 0,
  "ProtocolCur" : 0,
  "DelegateMin" : 0,
  "DelegateMax" : 0,
  "DelegateCur" : 0
}

GET /leave

Description

Force the node to leave the cluster.

Responses

HTTP Code Description Schema
200 Successful response < member > array

Tags

  • default

Example HTTP request

Request path
/leave

Example HTTP response

Response 200
json :
"array"

GET /members

Description

List members.

Responses

HTTP Code Description Schema
200 Successful response < member > array

Tags

  • members

Example HTTP request

Request path
/members

Example HTTP response

Response 200
json :
"array"

Definitions

status

Status represents details about the node.

Type : object

job

A Job represents a scheduled task to execute.

Name Description Schema
name
required
Name for the job.
Example : "string"
string
schedule
required
Cron expression for the job.
Example : "string"
string
command
required
Command to run.
Example : "string"
string
shell
optional
Use shell to run the command
Example : true
boolean
owner
optional
Owner of the job
Example : "string"
string
owner_email
optional
Email of the owner
Example : "string"
string
success_count
optional
read-only
Number of successful executions
Example : 0
integer
error_count
optional
read-only
Number of failed executions
Example : 0
integer
last_success
optional
read-only
Last time this job executed successfully
Example : "string"
string(date-time)
last_error
optional
read-only
Last time this job failed
Example : "string"
string(date-time)
disabled
optional
Disabled state of the job
Example : true
boolean
tags
optional
Target nodes tags of this job
Example : {<br> "string" : "string"<br>}
< string, string > map
retries
optional
Number of times to retry a failed job execution
Example : 2
integer
parent_job
optional
The name/id of the job that will trigger the execution of this job
Example : "parent_job"
string
dependent_jobs
optional
Array containing the jobs that depends on this one
Example : [ "string" ]
< string > array
processors
optional
Processor plugins used to process executions results of this job
Example : {<br> "string" : "string"<br>}
< string, string > map
concurrency
optional
Concurrency policy for the job allow/forbid
Example : "allow"
string

member

A member represents a cluster member node.

Name Description Schema
Name
optional
Node name
Example : "string"
string
Addr
optional
IP Address
Example : "string"
string
Port
optional
Port number
Example : 0
integer
Tags
optional
Tags asociated with this node
Example : {<br> "string" : "string"<br>}
< string, string > map
Status
optional
The serf status of the node see: https://godoc.org/github.com/hashicorp/serf/serf#MemberStatus
Example : 0
integer
ProtocolMin
optional
Serf protocol minimum version this node can understand or speak
Example : 0
integer
ProtocolMax
optional
Serf protocol maximum version this node can understand or speak
Example : 0
integer
ProtocolCur
optional
Serf protocol current version this node can understand or speak
Example : 0
integer
DelegateMin
optional
Serf delegate protocol minimum version this node can understand or speak
Example : 0
integer
DelegateMax
optional
Serf delegate protocol maximum version this node can understand or speak
Example : 0
integer
DelegateCur
optional
Serf delegate protocol current version this node can understand or speak
Example : 0
integer

execution

An execution represents a timed job run.

Name Description Schema
job_name
optional
job name
Example : "string"
string
started_at
optional
start time of the execution
Example : "string"
string(date-time)
finished_at
optional
when the execution finished running
Example : "string"
string(date-time)
success
optional
the execution run successfuly
Example : true
boolean
output
optional
partial output of the command execution
Example : "string"
string
node_name
optional
name of the node that executed the command
Example : "string"
string