swagger: '2.0'
######################################################
# Prolog
######################################################
info:
  version: "v1"
  title: "WSO2 Analytics - Job Manager"
  description: |
    This document specifies a **RESTful API** for WSO2 Analytics **Job Manager**.

    It is written with [swagger 2](http://swagger.io/).

  contact:
    name: "WSO2"
    url: "http://wso2.com/smart-analytics"
    email: "architecture@wso2.com"
  license: 
    name: "Apache 2.0"
    url: "http://www.apache.org/licenses/LICENSE-2.0.html"

######################################################
# The fixed parts of the URLs of the API
######################################################

# The schemes supported by the API
schemes: 
  - https
  - http

# The domain of the API.
# This is configured by the customer during deployment.
# The given host is just an example.
host: apis.wso2.com

# The base path of the API.
# Will be prefixed to all paths.
basePath: /api/das/jobmanager/v1

# The following media types can be passed as input in message bodies of the API.
# The actual media type must be specified in the Content-Type header field of the request.
# The default is json, i.e. the Content-Type header is not needed to
# be set, but supporting it serves extensibility.
consumes: 
  - application/json

# The following media types may be passed as output in message bodies of the API.
# The media type(s) consumable by the requestor is specified in the Accept header field
# of the corresponding request. 
# The actual media type returned will be specfied in the Content-Type header field 
# of the of the response.
# The default of the Accept header is json, i.e. there is not needed to
# set the value, but supporting it serves extensibility.
produces: 
  - application/json

#x-wso2-security:
#  apim:
#    x-wso2-scopes:
#      - description: ""
#        roles: Internal/subscriber
#        name: apim:subscribe
#        key: apim:subscribe

######################################################
# The "API Collection" resource APIs
######################################################
paths:
  /workers:

#-----------------------------------------------------
# Retrieving the list of all workers registered with Job Manager  
#-----------------------------------------------------
    get:
      summary: |
        Retrieving Workers
      description: |
        Get a list of registered workers.
      parameters:
        - $ref : "#/parameters/Accept"
      tags:
        - Workers
        - Retrieve
      responses:
        200:
          description: |
            OK.
            List of registered workers is returned.
          schema:
            $ref: '#/definitions/WorkerList'
          headers:
            Content-Type:
              description: The content type of the body.
              type: string
        406:
          description: |
            Not Acceptable.
            The requested media type is not supported
          schema:
            $ref: '#/definitions/Error'

#-----------------------------------------------------
# Registers a new Worker
#-----------------------------------------------------
    post:
      description: |
        Register a new Worker.
      parameters:
        - in: body
          name: body
          description: |
            Worker object that is to be created.
          required: true
          schema:
            $ref: '#/definitions/Worker'
        - $ref: '#/parameters/Content-Type'
      tags:
        - Worker (individual)
        - Register
      responses:
        201:
          description: |
            Registered.
            Successful response with the newly created object as entity in the body.
            Location header contains URL of newly created entity.
          schema:
            $ref: '#/definitions/Worker'
          headers:
            Location:
              description: |
                Location of the newly registered Worker.
              type: string
            Content-Type:
              description: |
                The content type of the body.
              type: string
        400:
          description: |
            Bad Request.
            Invalid request or validation error
          schema:
            $ref: '#/definitions/Error'
        409:
          description: |
            Conflict.
            Worker already exists.
          schema:
            $ref: '#/definitions/Error'
        415:
          description: |
            Unsupported media type.
            The entity of the request was in a not supported format.
          schema:
            $ref: '#/definitions/Error'

######################################################
# The "Individual Worker" resource
######################################################
  /workers/{id}:

#-----------------------------------------------------
# Retrieve the details of a Worker
#-----------------------------------------------------
    get:
      description: |
        Get details of a Worker
      parameters:
        - $ref: '#/parameters/id'
        - $ref: '#/parameters/Accept'
      tags:
        - Worker (individual)
        - Retrieve
      responses:
        200:
          description: |
            OK.
            Requested Worker is returned
          headers:
            Content-Type:
              description: |
                The content type of the body.
              type: string
          schema:
            $ref: '#/definitions/Worker'
        404:
          description: |
            Not Found.
            Requested Worker does not exist.
          schema:
            $ref: '#/definitions/Error'
        406:
          description: |
            Not Acceptable.
            The requested media type is not supported
          schema:
            $ref: '#/definitions/Error'

#-----------------------------------------------------
# Delete a certain worker
#-----------------------------------------------------
    delete:
      description: |
        Deregister a Worker
      parameters:
        - $ref: '#/parameters/id'
      tags:
        - Worker (individual)
        - Delete
      responses:
        200:
          description: |
            OK.
            Resource successfully deleted.
        404:
          description: |
            Not Found.
            Resource to be deleted does not exist.
          schema:
            $ref: '#/definitions/Error'

######################################################
# The "Execution Plans Collection" resource Workers
######################################################
  /workers/{id}/executionplans:

#-----------------------------------------------------
# Retrieve the execution plans associated with a Worker
#-----------------------------------------------------
    get:
      description: |
        Get a list of execution plans deployed in a Worker.
      parameters:
        - $ref: '#/parameters/id'
        - $ref: '#/parameters/Accept'
      tags:
        - Worker (individual)
        - Retrieve Execution Plans
      responses:
        200:
          description: |
            OK.
            Execution Plan list is returned.
          schema:
            $ref: '#/definitions/ExecutionPlanList'
          headers:
            Content-Type:
              description: |
                The content type of the body.
              type: string
        404:
          description: |
            Not Found.
            Requested Worker does not exist.
          schema:
            $ref: '#/definitions/Error'
        406:
          description: |
            Not Acceptable.
            The requested media type is not supported
          schema:
            $ref: '#/definitions/Error'

#-----------------------------------------------------
# Add a new execution plan to a Worker
#-----------------------------------------------------
    post:
      description: |
        Add a new execution plan to a Worker.
      parameters:
        - $ref: '#/parameters/id'
        - in: body
          name: body
          description: |
            Execution Plan object that is to be created.
          required: true
          schema:
            $ref: '#/definitions/ExecutionPlan'
        - $ref: '#/parameters/Content-Type'
      tags:
        - Worker (individual)
        - ExecutionPlan
        - Register
      responses:
        201:
          description: |
            Registered.
            Successful response with the newly created object as entity in the body.
            Location header contains URL of newly created entity.
          schema:
            $ref: '#/definitions/ExecutionPlan'
          headers:
            Location:
              description: |
                Location of the newly registered Execution Plan.
              type: string
            Content-Type:
              description: |
                The content type of the body.
              type: string
        400:
          description: |
            Bad Request.
            Invalid request or validation error
          schema:
            $ref: '#/definitions/Error'
        409:
          description: |
            Conflict.
            Worker already exists.
          schema:
            $ref: '#/definitions/Error'
        415:
          description: |
            Unsupported media type.
            The entity of the request was in a not supported format.
          schema:
            $ref: '#/definitions/Error'

######################################################
# Parameters - required by some of the APIs above
######################################################
parameters:

# Worker Identifier
# Specified as part of the path expression
  id:
    name: id
    in: path
    description: |
      **ID** consisting of the **UUID** of the Worker.
    required: true
    type: string

# The HTTP Accept header
  Accept:
    name: Accept
    in: header
    description: |
      Media types acceptable for the response. Default is JSON.
    default: JSON
    type: string

# The HTTP Content-Type header
  Content-Type:
    name: Content-Type
    in: header
    description: |
      Media type of the entity in the body. Default is JSON.
    default: JSON
    required: true
    type : string

######################################################
# The resources used by some of the APIs above within the message body
######################################################
definitions:

#-----------------------------------------------------
# The Worker List resource
#-----------------------------------------------------
  WorkerList:
    title: Worker List
    properties:
      list:
        type: array
        items:
          $ref: '#/definitions/Worker'

#-----------------------------------------------------
# The Worker resource
#-----------------------------------------------------
  Worker:
    title: Worker object with basic Worker details.
    properties:
      id:
        type: string
      ip:
        type: string
      port:
        type: string
      profile:
        type: string
      status:
        type: string

#-----------------------------------------------------
# The Execution Plan List resource
#-----------------------------------------------------
  ExecutionPlanList:
    title: Execution Plan List
    properties:
      list:
        type: array
        items:
          $ref: '#/definitions/ExecutionPlan'


#-----------------------------------------------------
# The Execution Plan resource
#-----------------------------------------------------
  ExecutionPlan:
    title: Execution Plan object
    properties:
      name:
        type: string

#-----------------------------------------------------
# The Error resource
#-----------------------------------------------------
  Error:
    title: Error object returned with 4XX HTTP lifeCycleStatus
    required:
      - code
      - message
    properties:
      code:
        type: integer
        format: int64
      message:
        type: string
        description: Error message.
      description:
        type: string
        description: |
          A detail description about the error message.
      moreInfo:
        type: string
        description: |
          Preferably an url with more details about the error.
      error:
        type: array
        description: |
          If there are more than one error list them out.
          For example, list out validation errors by each field.
        items:
          $ref: '#/definitions/ErrorListItem'

#-----------------------------------------------------
# The Error List Item resource
#-----------------------------------------------------
  ErrorListItem:
    title: Description of individual errors that may have occurred during a request.
    required:
      - code
      - message
    properties:
      code:
        type: string
      message:
        type: string
        description: |
          Description about individual errors occurred

#-----------------------------------------------------
# END-OF-FILE
#-----------------------------------------------------