swagger: '2.0'
basePath: /v1
host: localhost:8080
consumes:
  - application/json
produces:
  - application/json
schemes:
  - http
info:
  version: "3.0"
  title: Dkron REST API
  description: |
    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.

paths:
  /:
    get:
      description: |
        Gets `Status` object.
      operationId: status
      tags:
        - default
      responses:
        200:
          description: Successful response
          schema:
            $ref: '#/definitions/status'
  /jobs:
    get:
      description: |
        List jobs.
      parameters:
        - in: query
          name: metadata
          type: array
          collectionFormat: multi
          items:
            type: string
          description: Filter jobs by metadata
      operationId: getJobs
      tags:
        - jobs
      responses:
        200:
          description: Successful response
          schema:
            type: array
            items:
              $ref: '#/definitions/job'
    post:
      description: |
        Create or updates a new job.
      operationId: createOrUpdateJob
      tags:
        - jobs
      parameters:
        - in: body
          name: body
          description: Updated job object
          required: true
          schema:
            $ref: "#/definitions/job"
        - in: query
          name: runoncreate
          description: |
            If present, regardless of any value, causes the job to be run immediately after being succesfully created or updated.

            This will cause the server to wait until the job has finished before returning a result.
          required: false
          schema:
            type: boolean
          allowEmptyValue: true
      responses:
        201:
          description: Successful response
          schema:
            $ref: '#/definitions/job'
  /jobs/{job_name}:
    get:
      description: |
        Show a job.
      operationId: showJobByName
      tags:
        - jobs
      parameters:
        - in: path
          name: job_name
          description: The job that needs to be fetched.
          required: true
          type: string
      responses:
        200:
          description: Successful response
          schema:
            $ref: '#/definitions/job'
    delete:
      description: |
        Delete a job.
      operationId: deleteJob
      tags:
        - jobs
      parameters:
        - in: path
          name: job_name
          description: The job that needs to be deleted.
          required: true
          type: string
      responses:
        200:
          description: Successful response
          schema:
            $ref: '#/definitions/job'
    post:
      description: |
        Executes a job.

        The server will wait until the job has finished before returning a result.
      operationId: runJob
      tags:
        - jobs
      parameters:
        - in: path
          name: job_name
          description: The job that needs to be run.
          required: true
          type: string
      responses:
        202:
          description: Successful response
          schema:
            $ref: '#/definitions/job'
  /jobs/{job_name}/toggle:
    post:
      description: |
        Toggle a job.
      operationId: toggleJob
      tags:
        - jobs
      parameters:
        - in: path
          name: job_name
          description: The job that needs to be toggled.
          required: true
          type: string
      responses:
        200:
          description: Successful response
          schema:
            $ref: '#/definitions/job'
  /members:
    get:
      description: |
        List members.
      operationId: getMember
      tags:
        - members
      responses:
        200:
          description: Successful response
          schema:
            type: array
            items:
              $ref: '#/definitions/member'
  /leader:
    get:
      description: |
        List leader of cluster.
      operationId: getLeader
      tags:
        - default
      responses:
        200:
          description: Successful response
          schema:
            $ref: '#/definitions/member'
  /leave:
    post:
      description: |
        Force the node to leave the cluster.
      operationId: leave
      tags:
        - default
      responses:
        200:
          description: Successful response
          schema:
            type: array
            items:
              $ref: '#/definitions/member'
  /jobs/{job_name}/executions:
    get:
      description: |
        List executions.
      operationId: listExecutionsByJob
      tags:
        - executions
      parameters:
        - in: path
          name: job_name
          description: The job that owns the executions to be fetched.
          required: true
          type: string
      responses:
        200:
          description: Successful response
          schema:
            type: array
            items:
              $ref: '#/definitions/execution'

definitions:
  status:
    type: object
    description: "Status represents details about the node."
    readOnly: true
    properties:
      agent:
        description: "Node basic details"
        readOnly: true
        additionalProperties:
          type: object
      serf:
        description: "Serf status"
        readOnly: true
        additionalProperties:
          type: object
      tags:
        description: "Tags asociated with this node"
        readOnly: true
        additionalProperties:
          type: string
  job:
    type: object
    description: "A Job represents a scheduled task to execute."
    required:
    - name
    - schedule
    properties:
      name:
        type: string
        description: "Name for the job."
        readOnly: false
        example: "job1"
      displayname:
        type: string
        description: "Nice name for the job. Optional."
        readOnly: false
      schedule:
        type: string
        description: "Cron expression for the job."
        readOnly: false
        example: "@every 10s"
      timezone:
        type: string
        description: "Timezone where the job will be executed. By default and when field is set to empty string, the job will run in local time."
        readOnly: false
        example: "Europe/Berlin"
      owner:
        type: string
        description: "Owner of the job"
        readOnly: false
        example: "Platform Team"
      owner_email:
        type: string
        description: "Email of the owner"
        readOnly: false
        example: "platform@example.com"
      success_count:
        type: integer
        description: "Number of successful executions"
        readOnly: true
      error_count:
        type: integer
        description: "Number of failed executions"
        readOnly: true
      last_success:
        type: string
        format: date-time
        description: "Last time this job executed successfully"
        readOnly: true
      last_error:
        type: string
        format: date-time
        description: "Last time this job failed"
        readOnly: true
      disabled:
        type: boolean
        description: "Disabled state of the job"
        readOnly: false
      tags:
        type: object
        description: "Target nodes tags of this job"
        additionalProperties:
          type: string
        readOnly: false
        example:
          server: "true"
      metadata:
        type: object
        description: "Extra metadata tags for this job"
        additionalProperties:
          type: string
        readOnly: false
        example:
          office: "Barcelona"
      retries:
        type: integer
        description: "Number of times to retry a failed job execution"
        example: 2
        readOnly: false
      parent_job:
        type: string
        description: "The name/id of the job that will trigger the execution of this job"
        example: "parent_job"
        readOnly: false
      dependent_jobs:
        type: array
        items:
          type: string
        description: "Array containing the jobs that depends on this one"
        example: ['dependent_job']
        readOnly: true
      processors:
        $ref: '#/definitions/processors'
      concurrency:
        type: string
        description: "Concurrency policy for the job allow/forbid"
        example: "allow"
        readOnly: false
      executor:
        type: string
        description: "Executor plugin used to run the job"
        readOnly: false
        example: "shell"
      executor_config:
        type: object
        description: Executor plugin parameters
        additionalProperties:
          type: string
        example: 
          command: "echo 'Hello from Dkron'"
      status:
        type: string
        readOnly: true
        description: "Status of the job"
        example: "success"
  member:
    type: object
    description: A member represents a cluster member node.
    properties:
      Name:
        type: string
        description: "Node name"
        example: "dkron1"
      Addr:
        type: string
        description: "IP Address"
        example: "192.168.1.137"
      Port:
        type: integer
        description: "Port number"
        example: 8946
      Tags:
        type: object
        description: "Tags asociated with this node"
        additionalProperties:
          type: string
        example:
          rpc_addr: "192.168.1.137:6868"
          server: "true"
          version": "1.0.0"
      Status:
        type: integer
        description: "The serf status of the node see: https://godoc.org/github.com/hashicorp/serf/serf#MemberStatus"
        example: 1
      ProtocolMin:
        type: integer
        description: "Serf protocol minimum version this node can understand or speak"
        example: 5
      ProtocolMax:
        type: integer
        description: "Serf protocol maximum version this node can understand or speak"
        example: 2
      ProtocolCur:
        type: integer
        description: "Serf protocol current version this node can understand or speak"
        example: 2
      DelegateMin:
        type: integer
        description: "Serf delegate protocol minimum version this node can understand or speak"
      DelegateMax:
        type: integer
        description: "Serf delegate protocol maximum version this node can understand or speak"
        example: 5
      DelegateCur:
        type: integer
        description: "Serf delegate protocol current version this node can understand or speak"
        example: 4
  execution:
    type: object
    description: An execution represents a timed job run.
    properties:
      job_name:
        type: string
        description: "job name"
        example: "job_1"
      started_at:
        type: string
        format: date-time
        description: "start time of the execution"
      finished_at:
        type: string
        format: date-time
        description: "when the execution finished running"
      success:
        type: boolean
        description: "the execution run successfuly"
      output:
        type: string
        description: "partial output of the command execution"
        example: "Hello from Dkron"
      node_name:
        type: string
        description: "name of the node that executed the command"
        example: "dkron1"
  
  processors:
    type: object
    description: Processor plugins used to process executions results of this job
    additionalProperties:
      type: object
      additionalProperties:
        type: string
    example:
      files:
        forward: true