openapi: 3.0.3
info:
  title: OWLS API
  description: OpenWiFi Load Simulator API
  version: 0.2.0
  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: 
  - bearerAuth: []

tags:
- name: Login
  description: This is the firt call to make to obtain an access_token for all subsequent calls.
- name: OUIs
  description:
    OUIs represent the manufacturer of a hardware device. The first 3 bytes of a MAC address is the OUI.
    A single manufacturer may have a number of OUIs.
- name: Nodes
  description:
    Nodes represent the physical or virtual computers running the OWLS software. Nodes
    can be either a manager, a simulation node, or a monitor node.
- name: Manufacturers
  description:
    Manufacturers or makers of devices. Each manufacturer maybe assigned 1 or more OUI.
- name: CA
  description:
    Certificate authority (CA) is necessary to create keys for devices and services.
- name: Simulations
  description:
    A simulation holds the information details for a set of devices participating
    in a simulation.
- name: Actions
  description:
    Actions operate on simulations. They allow you to start, stop, cancel, or resume an existing simulation.
    This also allows you to specify the devices that should be targetted for the actions.
    This could be the word 'all' or a list of the devices in a simulation.
- name: Devices
  description:
    This lets you see the automatically created devices.
- name: Hardware
  description:
    This shows the previsouly defined hardware profiles for the created devices.

paths:
  /oauth2:
    post:
      tags: [ Login ]
      summary: Get access token - to be used as Bearer token header for all other API requests.
      operationId: getAccessToken
      requestBody:
        description: User id and password
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebTokenRequest'
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericGoodAnswer'
        403:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'

  /oauth2/{token}:
    delete:
      tags: [ Authentication ]
      summary: Revoke a token.
      operationId: removeAccessToken
      parameters:
        - in: path
          name: token
          schema:
            type:
              string
          required: true
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericGoodAnswer'
        404:
          $ref: '#/components/responses/NotFound'

  /ouis:
    get:
      tags: [ OUIs ]
      summary: Get the list of all available OUIs known by the system.
      operationId: getOUIs
      description: Retrieve a list or subset of all known OUIs in the system.
      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: Successfull 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 a specific 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: Successfull 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: Detailed version. This includes all the nodes and all the parameters.
          name: format
          schema:
            type: string
            enum: [detailed,nodes,simple]
          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 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: Successfull 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 manufacturer.
      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: Successfull 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. A CA can only be removed if no simulation is referencing it.
      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'
        428:
          description: CA cannot be deleted if it is in use.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimulationNameList'

  /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'

  /simulations/{id}/devices:
    get:
      tags: [ Devices ]
      summary: Get the list of all devices for a simulation.
      operationId: getSimulationDevicess
      description: test
      parameters:
        - in: path
          description: The name of the simulation we are interested in.
          name: id
          schema:
            type: string
          required: true
        - 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/SimulationDeviceList'
        403:
          $ref: '#/components/responses/Unauthorized'

  /simulations/{id}/state:
    get:
      tags: [ Simulations ]
      summary: Get the state for a simulation.
      operationId: getSimulationStateDetails
      description: Retrieve the simulation state details.
      parameters:
        - in: path
          description: The name of the simulation we are interested in.
          name: id
          schema:
            type: string
          required: true
      responses:
        200:
          description: Successful retrieval of simulation state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimulationStateDetails'
        403:
          $ref: '#/components/responses/Unauthorized'

  /simulations/{id}/devices/{serial}:
    get:
      tags: [ Devices ]
      operationId: getSimulationDevice
      description: Get the details of a single device.
      parameters:
        - in: path
          description: The name of the simulation we are interested in.
          name: id
          schema:
            type: string
          required: true
        - in: path
          description: The name of the simulation we are interested in.
          name: serial
          schema:
            type: string
          required: true
      responses:
        200:
          description: Successful retrieval of OUI array.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimulationDeviceDetails'
        403:
          $ref: '#/components/responses/Unauthorized'


  /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
                  enum: [start,stop,pause,cancel,resume]
                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'

  /actions/{id}:
    get:
      description: Get simulation action details
      tags: [ Actions ]
      summary: Get the status of a given job
      operationId: getActionsDetails
      parameters:
        - in: path
          description: The name of the simulation we are interested in.
          name: id
          schema:
            type: string
          required: true
      responses:
        200:
          description: Contains the details of the given action
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActionDetails'
        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:
    bearerAuth:        # arbitrary name for the security scheme
      type: http
      scheme: bearer
      bearerFormat: JWT
      
  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

    SimulationDeviceList:
      description: Manufacturer associated with an OUI.
      properties:
        SerialNumbers:
          type: array
          items:
            type: string

    SimulationDeviceDetails:
      description: Details of a specific device
      properties:
        simulation:
          type: string
        hardware_id:
          type: string
        serial:
          type: string
        ca:
          type: string
        bands:
          type: array
          items:
            type: string
        wan_mac:
          type: string
        lan_mac:
          type: string
        key:
          type: string
          format: byte
        cert:
          type: string
          format: byte
        wan_clients:
          type: array
          items:
            properties:
              index:
                type: integer
              band:
                type: string
              ssid:
                type: string
              mac:
                type: string
              vendor:
                type: string
        lan_clients:
          type: array
          items:
            properties:
              index:
                type: integer
              port:
                type: string
              mac:
                type: string
              vendor:
                type: string

    SimulationNameList:
      description: A list of simulation names
      properties:
        CAs:
          type: array
          items:
            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
        vendor_tip:
          type: string
        opensync:
          type: string
        number_of_radios:
          type: integer
        firmware_version:
          type: string
        firmware_profile:
          type: string
        firmware_image_inactive:
          type: string
        firmware_image_active:
          type: string
        firmware_host:
          type: string
        firmware_date:
          type: string
        firmware_commit:
          type: string
        firmware_build:
          type: string
        core:
          type: string
        channels_5GU:
          type: array
          items:
            type: integer
        channels_5GL:
          type: array
          items:
            type: integer
        channels_2G:
          type: array
          items:
            type: integer
        channel_default_5GU:
          type: integer
        channel_default_5GL:
          type: integer
        channel_default_2G:
          type: integer
        channel_backup_5GU:
          type: integer
        channel_backup_5GL:
          type: integer
        channel_backup_2G:
          type: integer
        bands:
          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: Details of a node
      readOnly: true
      properties:
        node:
          type: string
        processes:
          type: integer
        worst:
          type: number
        total:
          type: number
        allocated:
          type: number
        type:
          type: string

    SimulationStateDetails:
      description: Details of the state of a simulation
      readOnly: true
      properties:
        pushed:
          type: boolean
        current_operation:
          type: string
        state:
          type: string
        start_time:
          type: string
          format: date-time

    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
        execution_ms:
          type: integer

    WebTokenRequest:
      description: User Id and password.
      type: object
      required:
        - userId
        - password
      properties:
        userId:
          type: string
          default: support@example.com
        password:
          type: string
          default: support
      example:
        userId: support@example.com
        password: support

    WebTokenResult:
      description: Login and Refresh Tokens to be used in subsequent API calls.
      type: object
      properties:
        access_token:
          type: string
        refresh_token:
          type: string
        token_type:
          type: string
        expires_in:
          type: integer
          format: int32
        idle_timeout:
          type: integer
          format: int32
        aclTemplate:
          $ref: '#/components/schemas/WebTokenAclTemplate'

    WebTokenAclTemplate:
      type: object
      properties:
        aclTemplate:
          $ref: '#/components/schemas/AclTemplate'

    AclTemplate:
      type: object
      properties:
        Read:
          type: boolean
        ReadWrite:
          type: boolean
        ReadWriteCreate:
          type: boolean
        Delete:
          type: boolean
        PortalLogin:
          type: boolean