openapi: 3.0.0
info:
  title: OWLS API
  description: OpenWiFi Load Simulator API
  version: 0.0.1
  termsOfService:
    http://example.com/terms/
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  contact:
    name: Arilia Support
    email: owlsapisupport@arilia.com
    url: https://www.arilia.com/owlsapisupport

servers:
  - url: 'http://renegademac.arilia.com:9090/api/v1'
  - url: 'http://localhost:9090/api/v1'
  - url: 'http://debfarm1-node-b.arilia.com:9090/api/v1'

security: 
  - ApiKeyAuth: []

paths:
  /ouis:
    get:
      tags: [ OUIs ]
      summary: Get the list of all available OUIs as known by the system.
      operationId: getOUIs
      description: test
      parameters:
        - in: query
          description: Pagination start (starts at 1. If not specified, 1 is assumed)
          name: offset
          schema:
            type: integer
          required: false
        - in: query
          description: Maximum number of entries to return (if absent, no limit is assumed) 
          name: limit
          schema:
            type: integer
          required: false
        - in: query
          description: Filter the results
          name: filter
          schema:
            type: string
          required: false
      responses:
        200:
          description: Successful retrieval of OUI array.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OUIsPagination'
        403:
          $ref: '#/components/responses/Unauthorized'
          
  /ouis/{id}:
    get:
      tags: [ OUIs ]
      summary: Get the manufacturer associated with an OUI.
      operationId: getOUI
      parameters:
        - in: path
          description: 
            The OUI for which you want to find the manufacturer.
          name: 
            id
          schema:
            type: string
          required: 
            true
      responses:
        200:
          description: Successful retrieval of OUI array.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OUIMaker'
        403:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'
          
  /nodes:
    get:
      tags: [Nodes]
      summary: Retrieve the list of nodes available for the simulation.
      operationId: getNodeList
      parameters:
        - in: query
          description: Pagination start (starts at 1. If not specified, 1 is assumed)
          name: offset
          schema:
            type: integer
          required: false
        - in: query
          description: Maximum number of entries to return (if absent, no limit is assumed) 
          name: limit
          schema:
            type: integer
          required: false
        - in: query
          description: Filter the results
          name: filter
          schema:
            type: string
          required: false
        - in: query
          description: Detailed version
          name: details
          schema:
            type: integer
          required: false
        - in: query
          description: Detailed version
          name: types
          schema:
            type: integer
          required: false
      responses:
        200:
          description: The list of Nodes Currently connected.
          content: 
            application/json:
              schema:
                $ref: '#/components/schemas/NodeList'
                
  /vendors:
    get:
      tags: [ Manufacturers ]
      summary: Get the list of all available OUIs as known by the system for a given manufacturer.
      operationId: getManufacturers
      parameters:
        - in: query
          description: Pagination start (starts at 1. If not specified, 1 is assumed)
          name: offset
          schema:
            type: integer
          required: false
        - in: query
          description: Maximum number of entries to return (if absent, no limit is assumed) 
          name: limit
          schema:
            type: integer
          required: false
        - in: query
          description: Filter the results
          name: filter
          schema:
            type: string
          required: false
      responses:
        200:
          description: Successful retrieval of OUI array.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MakerList'
        403:
          $ref: '#/components/responses/Unauthorized'

  /vendors/{id}:
    get:
      tags: [ Manufacturers ]
      summary: Get the OUIs associated with a maker.
      operationId: getManufacturer
      parameters: 
        - in: path
          description: The OUI for which you want to find the manufacturer.
          name: id
          schema:
            type: string
          required: true
      responses:
        200:
          description: Successful retrieval of OUI array.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MakerOUIList'
        403:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'
                
  /cas:
    get:
      tags: [ CA ]
      summary: Get a list of existing CAs
      operationId: getCAs
      parameters:
        - in: query
          description: Pagination start (starts at 1. If not specified, 1 is assumed)
          name: offset
          schema:
            type: integer
          required: false
        - in: query
          description: Maximum number of entries to return (if absent, no limit is assumed) 
          name: limit
          schema:
            type: integer
          required: false
        - in: query
          description: Filter the results
          name: filter
          schema:
            type: string
          required: false

      responses:
        200:
          description: Return the list of CAs.This can be an empty list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CAsPagination'
        403:
          $ref: '#/components/responses/Unauthorized'

  /cas/{id}:
    get:
      tags: [CA]
      summary: Get the details about a single CA
      operationId: getASingleCA
      parameters: 
        - in: path
          description: The name of the CA we are interested in.
          name: id
          schema:
            type: string
          required: true
      responses:
        200:
          description: Details of the requested CA
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CADetails'
        403:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'

    post:
      tags: [CA]
      summary: Create a new CA
      operationId: createCA
      parameters: 
        - in: path
          description: The name of the CA we are interested in.
          name: id
          schema:
            type: string
          required: true
      requestBody:
        description: The information about the CA
        required: true
        content:
          application/json:
            schema:
              properties:
                name:
                  type: string
                key:
                  type: string
                cert:
                  type: string
                password:
                  type: string
      responses:
        201:
          description: Creation of a CA success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CADetails'
        204:
          description: Update of a CA success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CADetails'
        403:
          $ref: '#/components/responses/Unauthorized'

    delete:
      tags: [CA]
      summary: Remove all information about a given CA
      operationId: RemoveCA
      parameters:
        - in: path
          description: The name of the CA to remove
          name: id
          schema:
            type: string
          required: true
      responses:
        200:
          description: Succesful removal of CA
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericGoodAnswer'
        403:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'


  /simulations:
    get:
      tags: [Simulations]
      summary: List all existing simulations
      operationId: listSimulations
      parameters:
        - in: query
          description: Pagination start (starts at 1. If not specified, 1 is assumed)
          name: offset
          schema:
            type: integer
          required: false
        - in: query
          description: Maximum number of entries to return (if absent, no limit is assumed) 
          name: limit
          schema:
            type: integer
          required: false
        - in: query
          description: Filter the results
          name: filter
          schema:
            type: string
          required: false

      responses:
        200:
          description: Return the list of simulations.This can be an empty list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimulationsPagination'
        403:
          $ref: '#/components/responses/Unauthorized'

  /simulations/{id}:
    get:
      tags: [Simulations]
      summary: Get the details about a single simulation
      operationId: getASingleSimulation
      parameters: 
        - in: path
          description: The name of the simulation we are interested in.
          name: id
          schema:
            type: string
          required: true
      responses:
        200:
          description: Details of the requested simulation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimulationDetails'
        403:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'

    post:
      tags: [Simulations]
      summary: Update the details about a single CA
      operationId: createASingleSimulation
      parameters: 
        - in: path
          description: The name of the simulation we are creating.
          name: id
          schema:
            type: string
          required: true
      requestBody:
        description: The information about the device
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SimulationDetails'
      responses:
        200:
          description: Return on success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimulationDetails'
        201:
          description: Return on success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimulationDetails'
        204:
          description: Return on success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimulationDetails'
        403:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'

    delete:
      tags: [Simulations]
      summary: Remove all information about a given simulation
      operationId: removeSimulation
      parameters:
        - in: path
          description: The name of the simulation to remove
          name: id
          schema:
            type: string
          required: true
      responses:
        200:
          $ref: '#/components/responses/Success'
        403:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'

  /hardware_definitions:
    get:
      tags: [ Hardware ]
      summary: Get the list of all available hardware as known by the system.
      operationId: getHardwares
      description: Hardware definitions
      parameters:
        - in: query
          description: Pagination start (starts at 1. If not specified, 1 is assumed)
          name: offset
          schema:
            type: integer
          required: false
        - in: query
          description: Maximum number of entries to return (if absent, no limit is assumed) 
          name: limit
          schema:
            type: integer
          required: false
        - in: query
          description: Filter the results
          name: filter
          schema:
            type: string
          required: false
      responses:
        200:
          description: Successful retrieval of Hardware Defintions array.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HardwareDefinitionsList'
        403:
          $ref: '#/components/responses/Unauthorized'
          
  /actions:
    get:
      description: List simulation actions
      tags: [ Actions ]
      summary: List all outstdnaing or completed actions
      operationId: getActions
      parameters:
        - in: query
          description: Pagination start (starts at 1. If not specified, 1 is assumed)
          name: offset
          schema:
            type: integer
          required: false
        - in: query
          description: Maximum number of entries to return (if absent, no limit is assumed) 
          name: limit
          schema:
            type: integer
          required: false
      responses:
        200:
          description: Contains the list of currently outstanding actions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActionList'
        403:
          $ref: '#/components/responses/Unauthorized'
    
    post:
      description: Launch an action
      tags: [ Actions ]
      summary: Create an action for the simulation
      operationId: createAction
      requestBody:
        description: The information about the device
        required: true
        content:
          application/json:
            schema:
              properties:
                # only actions supported are
                # prepare,push,start,stop,pause,cancel,restart
                action:
                  type: string
                simulation:
                  type: string
                parameters:
                # Only supported parameter is stagger
                # Only supported value is X/Y
                # where X and Y are integers
                # X is the number of devices
                # Y is over which interval in ms
                # 2/2000 means 2 devices per 2000ms (2s)
                  type: array
                  items:
                    properties:
                      name:
                        type: string
                      value:
                        type: string
      
      responses:
        200:
          description: Success after posting an action
          content:
            application/json:
              schema:
                properties:
                  action:
                    type: string
                  simulation:
                    description: Simulation name associated with the action.
                    type: string
                  id:
                    description: ID givent to the action.
                    type: string
        403:
          $ref: '#/components/responses/Unauthorized'

components:
  responses:
    NotFound:
      description: The specified resource was not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GenericErrorResponse'
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GenericErrorResponse'
    Success:
      description: Success
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GenericGoodAnswer'

  securitySchemes:
    ApiKeyAuth:        # arbitrary name for the security scheme
      type: apiKey
      in: header       
      name: X-API-KEY 
      
  schemas:
    GenericErrorResponse:
      description: Typical error response
      properties:
        ErrorCode:
          type: integer
        ErrorDetails:
          type: string
        ErrorDescription:
          type: string
          
    GenericGoodAnswer:
      description: used for all succesful responses.
      properties:
        Operation:
          type: string
        Details:
          type: string
        Code:
          type: integer
            
    OUIList:
      description: List of OUIs.
      properties:
        OUIs:
          type: array
          items:
            type: string
          
    MakerList:
      description: List of Manufacturers.
      properties:
        Manufacturers:
          type: array
          items: 
            type: string
            
    MakerOUIList:
      description: OUIs associated with a manufacturer.
      properties:
        Manufacturer:
          type:
            string
        OUIs:
          type: array
          items:
            type: string
          
    OUIMaker:
      description: Manufacturer associated with an OUI.
      properties:
        OUI:
          type:
            string
        Manufacturer:
            type: 
              string
              
    CAList:
      description: A list of CAs
      properties:
        CAs:
          type: array
          items:
            type: string
            
    CADetails:
      description: Details information about a CA
      properties:
        Name: 
          description: Name of the CA (may not contains special characters)
          type: string
        Key:
          description: The key for the CA
          type: string
          format: byte
        Cert:
          description: The certificate for the CA
          type: string
          format: byte

    HardwareDefinitionsList:
      description: List of hardware definitions
      readOnly: true
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/HardwareDefinitions'
            
    HardwareDefinitions:
      description: Hardware details
      readOnly: true
      properties:
        id: 
          type: string
        description:
          type: string
        vendor:
          type: string
        model:
          type: string
        firmware:
          type: string
        capabilities:
          type: array
          items:
            type: string
        
    PaginationInfo:
      description: Optional information about pagination during bulk operations
      readOnly: true
      properties:
        Limit:
          description: Selected limit
          type: integer
        Offset:
          description: Starting point
          type: integer
        PreviousOffset:
          description: the previous offset or null if there is none
          type: integer
        NextOffset: 
          description: the next offset or null if there is none
          type: integer
        CurrentPage: 
          description: the current page or null if it does not exist (e.g., out of bounds)
          type: integer
        PageCount: 
          description: the total number of pages
          type: integer
        TotalCount: 
          description: the total number of elements in the collection
          type: integer

    CAsPagination:
      description: Returning a list of CAs
      readOnly: true
      properties:
        Data:
          $ref: '#/components/schemas/CAList'
        Meta:
          $ref: '#/components/schemas/PaginationInfo'

    SimulationsPagination:
      description: Returning a list of Simulations
      readOnly: true
      properties:
        Data:
          $ref: '#/components/schemas/SimulationList'
        Meta:
          $ref: '#/components/schemas/PaginationInfo'
          
    OUIsPagination:
      description: Returning a list of OUIs
      readOnly: true
      properties:
        Data: 
          $ref: '#/components/schemas/OUIList'
        Meta:
          $ref: '#/components/schemas/PaginationInfo'

    DetailedNodeList:
      description: Detailed list of nodes.
      readOnly: true
      properties:
        data:
          description: Node list
          type: array
          items:
            $ref: '#/components/schemas/NodeDetails'
        Meta:
          $ref: '#/components/schemas/PaginationInfo'

    SimulationList:
      description: List of simulations
      readOnly: true
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/SimulationDetails'
                
    NodeDetails:
      description: Detaails of a node
      readOnly: true
      properties:
        node:
          type: string
        processes:
          type: integer
        worst:
          type: number
        total:
          type: number
        allocated:
          type: number
        type:
          type: string
        
    SimulationDetails:
      description: Details of the simulation
      properties:
        name:
          description: Name of the simulation
          type: string
        caname:
          description: CA Associated with the simulation (must exist)
          type: string
        num_devices:
          description: Number of devices for this simulation
          type: integer
        nodes:
          type: array
          items:
            type: string
        server:
          type: string
        port:
          type: integer
        creation_date:
          type: string
          readOnly: true
        assets_created:
          type: boolean
          readOnly: true

    NodeList:
      description: List of nodes.
      readOnly: true
      properties:
        Nodes:
          description: Node list
          type: array
          oneOf:
            - type: string
            - $ref: '#/components/schemas/DetailedNodeList'
          items:
            type: string
        Meta:
          $ref: '#/components/schemas/PaginationInfo'        
          
    ActionList:
      description: List of actions
      readOnly: true
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ActionDetails'
            
    ActionDetails:
      description: Action details
      readOnly: true
      properties:
        id: 
          type: string
        operation:
          type: string
        parameters:
          type: array
          items:
            properties:
              name:
                type: string
              value:
                type: string
        status:
          type: string
        created:
          type: string
          format: date
        completed:
          type: string
          format: date
        done_count:
          type: integer
        target_count:
          type: integer