openapi: 3.0.0
info:
  title: SEAMM Dashboard API
  description: This is an API for the SEAMM dashboard.
  contact:
    email: janash@vt.edu
  version: "1.0.0"
servers: 
  - url: /api
tags:
- name: admins
  description: Secured Admin-only calls
- name: developers
  description: Operations available to regular developers
paths:
  /jobs/{id}:
    get:
      tags:
      - developers
      summary: searches jobs database by id
      description: |
        Get jobs. By passing parameters you can get jobs fitting a certain criteria.
      operationId: seamm_dashboard.routes.api.get_job
      parameters:
      - name: id
        in: path
        description: retrieve job by id.
        required: true
        style: simple
        explode: false
        schema:
          type: integer
      responses:
        "200":
          description: search results matching criteria
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Job'
        "400":
          description: bad input parameter
    put:
      tags:
      - admins
      operationId: seamm_dashboard.routes.api.update_job
      parameters:
      - name: id
        in: path
        description: update job by id.
        required: true
        style: simple
        explode: false
        schema:
          type: integer
      requestBody:
        description: Job values to update
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: item updated
        "400":
          description: invalid input, object invalid
    delete:
      tags:
      - admins
      operationId: seamm_dashboard.routes.api.delete_job
      parameters:
      - name: id
        in: path
        description: ID of the job to delete.
        required: true
        style: simple
        explode: false
        schema:
          type: integer
      responses:
        "200":
          description: Job deleted successfully.
        "404":
          description: Job not found.
  /jobs/{id}/files:
    get:
      tags:
      - developers
      summary: returns json of files associated with a particular job
      description: |
        Get job files.
      operationId: seamm_dashboard.routes.api.get_job_files
      parameters:
      - name: id
        in: path
        description: retrieve job by id.
        required: true
        style: simple
        explode: false
        schema:
          type: integer
      - name: file_path
        in: query
        schema: 
          type: string
        description: Retrieve text for file.
      responses:
        "200":
          description: search results matching criteria
        "400":
          description: bad input parameter
  /jobs:
    get:
      tags:
      - developers
      summary: searches jobs database
      description: |
        Get jobs. By passing parameters you can get jobs fitting a certain criteria.
      operationId: seamm_dashboard.routes.api.get_jobs
      parameters:
      - name: createdSince
        in: query
        description: look for jobs created since a date.
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: createdBefore
        in: query
        description: look for jobs created before a date.
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: limit
        in: query
        description: maximum number of records to return
        required: false
        style: form
        explode: true
        schema:
          minimum: 1
          type: integer
          format: int32
      responses:
        "200":
          description: search results matching criteria
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Job'
        "400":
          description: bad input parameter
    post:
      tags:
      - developers
      summary: submit a job
      description: |
        Submits a new job to the system
      operationId: seamm_dashboard.routes.api.add_job
      requestBody:
        description: The job being submitted.
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - username
                - flowchart
              properties:
                username:
                  type: string
                project:
                  type: string
                flowchart:
                  type: string
                title:
                  type: string
                description:
                  type: string
      responses:
        "201":
          description: id of submitted job
          content:
            application/json:
              schema:
                properties:
                  id:
                    type: integer
                    example: 53
                  path:
                    type: string
                    format: filepath
                    example: /Users/username/seamm/projects/username/Job000053
        "400":
          description: bad input parameter
        "403":
          description: user not registered
        "422":
          description: error validating job data
  /flowcharts:
    get:
      tags:
      - developers
      summary: searches flowcharts database
      description: |
        Get flowcharts
      operationId: seamm_dashboard.routes.api.get_flowcharts
      parameters:
      - name: description
        in: query
        schema: 
          type: string
        description: Search within flowchart description.
      - name: limit
        in: query
        description: maximum number of records to return
        required: false
        style: form
        explode: true
        schema:
          minimum: 1
          type: integer
          format: int32
      responses:
        "200":
          description: search results matching criteria
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Flowchart'
        "400":
          description: bad input parameter
  /flowcharts/{id}:
    get:
      tags:
      - developers
      summary: searches database by flowchart id
      description: |
        Get flowchart by ID.
      operationId: seamm_dashboard.routes.api.get_flowchart
      parameters:
      - name: id
        in: path
        description: retrieve flowchart by id.
        required: true
        style: simple
        explode: false
        schema:
          type: string
      responses:
        "200":
          description: search results matching criteria
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Flowchart'
        "400":
          description: bad input parameter
  /flowcharts/{id}/cytoscape:
    get:
      tags:
      - developers
      summary: searches database by flowchart id
      description: |
        Get flowchart by ID.
      operationId: seamm_dashboard.routes.api.get_cytoscape
      parameters:
      - name: id
        in: path
        description: retrieve flowchart by id.
        required: true
        style: simple
        explode: false
        schema:
          type: string
      responses:
        "200":
          description: search results matching criteria
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Flowchart'
        "400":
          description: bad input parameter
  /projects:
    get:
      tags:
      - developers
      summary: searches projects database
      description: |
        Get projects
      operationId: seamm_dashboard.routes.api.get_projects
      parameters:
      - name: description
        in: query
        schema: 
          type: string
        description: Search within project description.
      - name: limit
        in: query
        description: maximum number of records to return
        required: false
        style: form
        explode: true
        schema:
          minimum: 1
          type: integer
          format: int32
      responses:
        "200":
          description: search results matching criteria
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Project'
        "400":
          description: bad input parameter
  /projects/{id}:
    get:
      tags:
      - developers
      summary: searches database by project id
      description: |
        Get project by ID.
      operationId: seamm_dashboard.routes.api.get_project
      parameters:
      - name: id
        in: path
        description: retrieve project by id.
        required: true
        style: simple
        explode: false
        schema:
          type: string
      responses:
        "200":
          description: search results matching criteria
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Project'
        "400":
          description: bad input parameter
  /projects/{id}/jobs:
    get:
      tags:
      - developers
      summary: retrieves jobs associated with a project
      description: |
        Get jobs associated with a project by project ID.
      operationId: seamm_dashboard.routes.api.get_project_jobs
      parameters:
      - name: id
        in: path
        description: retrieve project by id.
        required: true
        style: simple
        explode: false
        schema:
          type: string
      responses:
        "200":
          description: search results matching criteria
          content:
            application/json:
              schema:
                type: array
        "400":
          description: bad input parameter
  /groups:
    get:
      tags:
      - admin
      - managers
      summary: retrieves dashboard groups
      operationId: seamm_dashboard.routes.api.get_groups
      responses:
        "200":
          description: users listed
        "403":
          description: permission denied 
  /roles:
    get:
      tags:
      - admin
      - managers
      summary: retrieves dashboard groups
      operationId: seamm_dashboard.routes.api.get_roles
      responses:
        "200":
          description: users listed
        "403":
          description: permission denied 
  /users:
    get:
      tags:
      - admin
      summary: retrieves users of dashboard
      description: |
        Get jobs associated with a project by project ID.
      operationId: seamm_dashboard.routes.api.get_users
      responses:
        "200":
          description: users listed
        "403":
          description: permission denied 
    post:
      tags:
      - admins
      summary: create a user
      description: |
        Adds a new user to the dashboard
      operationId: seamm_dashboard.routes.api.add_user
      requestBody:
        description: The username and password of the new user.
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - username
                - password
              properties:
                username:
                  type: string
                password:
                  type: string
      responses:
        "201":
          description: id of created user
          content:
            application/json:
              schema:
                properties:
                  id:
                    type: integer
                    example: 53
        "400":
          description: bad input parameter
        "403":
          description: user not registered
        "422":
          description: error validating job data

  /status:
    get:
      summary: return the status of the dashboard
      description: |
        Return the status of the dashboard. Currently 'running' |
        but in the furtire may return other status strings.
      operationId: seamm_dashboard.routes.api.status
      responses:
        "200":
          description: the status
          content:
            text/plain:
              schema:
                type: string
  /api/auth/token/remove:
    get:
      summary: remove auth token.
      operationId: seamm_dashboard.routes.api.remove_auth_token
      responses:
        "200":
          description: successfully logged out
          content:
            text/plain:
              schema:
                type: string
  /auth/token:
    post:
      summary: post username and password and get a token for the current user
      description: |
        Return a token to be used for authentication
      operationId: seamm_dashboard.routes.api.get_auth_token
      requestBody:
        description: The username and password of the new user.
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - username
                - password
              properties:
                username:
                  type: string
                password:
                  type: string
      responses:
        "200":
          description: Login successful.
        "400":
          description: Bad credentials
  /auth/token/refresh:
    post:
      summary: Refresh the access token
      description: |
        Return a token to be used for authentication. An old token will be
      operationId: seamm_dashboard.routes.api.refresh_auth_token
      responses:
        "200":
          description: Token refreshed.
        "400":
          description: Bad credentials
components:
  schemas:
    Flowchart:
      required:
      - flowchart_file
      - flowchart_json
      - id
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: d290f1ee-6c54-4b01-90e6-d701748f0851
        flowchart_file:
          type: string
        flowchart_json:
          type: string
    Job:
      required:
      - flowchart_id
      - id
      - path
      - submission_date
      type: object
      properties:
        id:
          type: integer
          example: 1
        path:
          type: string
          format: filepath
          example: /Users/username/seamm/projects
        flowchart_id:
          type: string
        submission_date:
          format: date-time
          example: 2016-08-29T09:12:33.001Z
    Project:
      required:
      - id
      - path
      - name
      type: object
      properties:
        id:
          type: integer
          example: 1
        path:
          type: string
          format: filepath
          example: /Users/username/seamm/projects
        name:
          type: string
          example: MyProject
      
