openapi: 3.0.1
info:
  title: OpenWiFi User Portal
  description: API describing User Self Care interaction with OpenWifi.
  version: 1.0.0
  license:
    name: BSD3
    url: https://github.com/Telecominfraproject/wlan-cloud-ucentralgw/blob/master/LICENSE

servers:
  - url: 'https://localhost:16006/api/v1'

security:
  - bearerAuth: []
  - ApiKeyAuth: []

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  responses:
    NotFound:
      $ref: 'https://github.com/Telecominfraproject/wlan-cloud-ucentralsec/blob/main/openpapi/owsec.yaml#/components/responses/NotFound'
    Unauthorized:
      $ref: 'https://github.com/Telecominfraproject/wlan-cloud-ucentralsec/blob/main/openpapi/owsec.yaml#/components/responses/Unauthorized'
    Success:
      $ref: 'https://github.com/Telecominfraproject/wlan-cloud-ucentralsec/blob/main/openpapi/owsec.yaml#/components/responses/Success'
    BadRequest:
      $ref: 'https://github.com/Telecominfraproject/wlan-cloud-ucentralsec/blob/main/openpapi/owsec.yaml#/components/responses/BadRequest'

  schemas:
    HomeDeviceMode:
      type: object
      properties:
        type:
          type: string
          enum:
            - bridge
            - manual
            - nat
          default: automatic
        ipV6Support:
          type: boolean
          default: false
        enableLEDS:
          type: boolean
          default: true
        subnet:
          type: string
          format: ipv4
        subnetMask:
          type: integer
          format: int32
        startIP:
          type: string
          format: ipv4
        endIP:
          type: string
          format: ipv4
        subnetV6:
          type: string
          format: ipv6
        subnetMaskV6:
          type: integer
          format: int32
        startIPV6:
          type: string
          format: ipv6
        endIPV6:
          type: string
          format: ipv6
        created:
          type: integer
          format: int64
        modified:
          type: integer
          format: int64
        leaseTime:
          type: string

    IPReservation:
      type: object
      properties:
        nickname:
          type: string
        ipAddress:
          type: string
          example: maybe IPv4 or IPv6
        macAddress:
          type: string
          format: mac-address

    IPReservationList:
      type: object
      properties:
        created:
          type: integer
          format: int64
        modified:
          type: integer
          format: int64
        reservations:
          type: array
          items:
            $ref: '#/components/schemas/IPReservation'

    DnsConfiguration:
      type: object
      properties:
        ISP:
          type: boolean
        custom:
          type: boolean
        primary:
          type: string
          format: ipv4
        secondary:
          type: string
          format: ipv4
        primaryV6:
          type: string
          format: ipv6
        secondaryV6:
          type: string
          format: ipv6

    InternetConnection:
      type: object
      properties:
        type:
          type: string
          enum:
            - manual
            - pppoe
            - automatic
        ipV6Support:
          type: boolean
          default: false
        username:
          type: string
        password:
          type: string
        ipAddress:
          type: string
          format: ipv4
        subnetMask:
          type: string
          format: ipv4
        defaultGateway:
          type: string
          format: ipv4
        primaryDns:
          type: string
          format: ipv4
        secondaryDns:
          type: string
          format: ipv4
        ipAddressV6:
          type: string
          format: ipv6
        subnetMaskV6:
          type: integer
          format: int32
        defaultGatewayV6:
          type: string
          format: ipv6
        primaryDnsV6:
          type: string
          format: ipv6
        secondaryDnsV6:
          type: string
          format: ipv6
        created:
          type: integer
          format: int64
        modified:
          type: integer
          format: int64

    WifiNetwork:
      type: object
      properties:
        type:
          type: string
          enum:
            - main
            - guest
        name:
          type: string
          maxLength: 32
        password:
          type: string
          minLength: 8
          maxLength: 32
        encryption:
          type: string
          enum:
            - wpa1-personal
            - wpa2-personal
            - wpa3-personal
            - wpa1/2-personal
            - wpa2/3-personal
          default: wpa2-personal
        bands:
          type: array
          items:
            type: string
            enum:
              - all
              - 2G
              - 5G
              - 5GL
              - 5GU
              - 6G

    WifiNetworkList:
      type: object
      properties:
        created:
          type: integer
          format: int64
        modified:
          type: integer
          format: int64
        networks:
          type: array
          items:
            $ref: '#/components/schemas/WifiNetwork'

    AccessTime:
      type: object
      properties:
        description:
          type: string
        day:
          type: string
        rangeList:
          type: array
          items:
            type: string

    AccessTimes:
      type: object
      properties:
        description:
          type: string
        created:
          type: integer
          format: int64
        modified:
          type: integer
          format: int64
        schedule:
          type: array
          items:
            $ref: '#/components/schemas/AccessTime'

    SubscriberDevice:
      type: object
      properties:
        name:
          type: string
        description:
          type: string
        macAddress:
          type: string
        manufacturer:
          type: string
        firstContact:
          type: integer
          format: int64
        lastContact:
          type: integer
          format: int64
        group:
          type: string
        icon:
          type: string
          format: uuid
        suspended:
          type: boolean
        ip:
          type: string
        created:
          type: integer
          format: int64
        modified:
          type: integer
          format: int64
        schedule:
          $ref: '#/components/schemas/AccessTimes'

    SubscriberDeviceList:
      type: object
      properties:
        created:
          type: integer
          format: int64
        modified:
          type: integer
          format: int64
        devices:
          type: array
          items:
            $ref: '#/components/schemas/SubscriberDevice'

    Association:
      type: object
      properties:
        name:
          type: string
        ssid:
          type: string
        macAddress:
          type: string
        rssi:
          type: integer
        power:
          type: integer
        ipv4:
          type: string
        ipv6:
          type: integer
        tx:
          type: integer
        rx:
          type: integer
        manufacturer:
          type: string

    AssociationList:
      type: object
      properties:
        created:
          type: integer
          format: int64
        modified:
          type: integer
          format: int64
        associations:
          type: array
          items:
            $ref: '#/components/schemas/Association'

    Client:
      type: object
      properties:
        macAddress:
          type: string
        speed:
          type: string
        mode:
          type: string
        ipv4:
          type: string
        ipv6:
          type: integer
        tx:
          type: integer
        rx:
          type: integer
        manufacturer:
          type: string

    ClientList:
      type: object
      properties:
        created:
          type: integer
          format: int64
          readOnly: true
        modified:
          type: integer
          format: int64
          readOnly: true
        clients:
          type: array
          items:
            $ref: '#/components/schemas/Client'

    Location:
      type: object
      properties:
        buildingName:
          type: string
        addressLines:
          type: array
          items:
            type: string
        city:
          type: string
        state:
          type: string
        postal:
          type: string
        country:
          type: string
        phones:
          type: array
          items:
            type: string
        mobiles:
          type: array
          items:
            type: string

    RadioRates:
      type: object
      properties:
        beacon:
          type: integer
          default: 6000
          enum:
            - 0
            - 1000
            - 2000
            - 5500
            - 6000
            - 9000
            - 11000
            - 12000
            - 18000
            - 24000
            - 36000
            - 48000
            - 54000
        multicast:
          type: integer
          default: 24000
          enum:
            - 0
            - 1000
            - 2000
            - 5500
            - 6000
            - 9000
            - 11000
            - 12000
            - 18000
            - 24000
            - 36000
            - 48000
            - 54000

    RadioHE:
      type: object
      properties:
        multipleBSSID:
          type: boolean
          default: false
        ema:
          type: boolean
          default: false
        bssColor:
          type: integer
          default: 64

    RadioInformation:
      type: object
      properties:
        band:
          type: string
          enum:
            - 2G
            - 5G
            - 5GL
            - 5GU
            - 6G
        bandwidth:
          type: integer
          enum:
            - 5
            - 10
            - 20
        channel:
          oneOf:
            - type: integer
              minimum: 1
              maximum: 171
            - type: string
              enum:
                - auto
        country:
          type: string
          minLength: 2
          maxLength: 2
        channelMode:
          type: string
          enum:
            - HT
            - VHT
            - HE
          default: HE
        channelWidth:
          type: integer
          enum:
            - 20
            - 40
            - 80
            - 160
            - 8080
          default: 80
        requireMode:
          type: string
          enum:
            - HT
            - VHT
            - HE
        txPower:
          type: integer
          minimum: 0
          maximum: 30
        legacyRates:
          type: boolean
          default: false
        beaconInterval:
          type: integer
          minimum: 15
          maximum: 65535
          default: 100
        dtimPeriod:
          type: integer
          default: 2
          minimum: 1
          maximum: 255
        rates:
          $ref: '#/components/schemas/RadioRates'
        he:
          $ref: '#/components/schemas/RadioHE'
        rawInfo:
          type: array
          items:
            type: string

    AccessPoint:
      type: object
      properties:
        id:
          type: string
          format: uuid
        macAddress:
          type: string
        serialNumber:
          type: string
        name:
          type: string
        deviceType:
          type: string
        subscriberDevices:
          $ref: '#/components/schemas/SubscriberDeviceList'
        ipReservations:
          $ref: '#/components/schemas/IPReservationList'
        address:
          $ref: '#/components/schemas/Location'
        wifiNetworks:
          $ref: '#/components/schemas/WifiNetworkList'
        internetConnection:
          $ref: '#/components/schemas/InternetConnection'
        deviceMode:
          $ref: '#/components/schemas/HomeDeviceMode'
        dnsConfiguration:
          $ref: '#/components/schemas/DnsConfiguration'
        radios:
          type: array
          items:
            $ref: '#/components/schemas/RadioInformation'
        automaticUpgrade:
          type: boolean
          default: true
        configurationUUID:
          type: string
          format: uuid
          readOnly: true
        currentFirmware:
          type: string
        currentFirmwareDate:
          type: integer
        latestFirmware:
          type: string
        latestFirmwareDate:
          type: integer
        newFirmwareAvailable:
          type: boolean

    AccessPointList:
      type: object
      properties:
        list:
          type: array
          items:
            $ref: '#/components/schemas/AccessPoint'

    SubscriberInfo:
      type: object
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        userId:
          type: string
          format: email
          readOnly: true
        firstName:
          type: string
        initials:
          type: string
        lastName:
          type: string
        phoneNumber:
          type: string
        secondaryEmail:
          type: string
          format: email
        accessPoints:
          $ref: '#/components/schemas/AccessPointList'
        serviceAddress:
          $ref: '#/components/schemas/Location'
        billingAddress:
          $ref: '#/components/schemas/Location'
        created:
          type: integer
          format: int64
          readOnly: true
        modified:
          type: integer
          format: int64
          readOnly: true

    PasswordChange:
      type: object
      properties:
        oldPassword:
          type: string
          format: password
        newPassword:
          type: string
          format: password

    PasswordCreation:
      type: object
      properties:
        newPassword:
          type: string
          format: password

    MFAChallengeRequest:
      type: object
      properties:
        uuid:
          type: string
          format: uuid
        question:
          type: string
        created:
          type: integer
          format: integer64
        method:
          type: string

    MFAChallengeResponse:
      type: object
      properties:
        uuid:
          type: string
          format: uuid
        answer:
          type: string

    WebTokenRefreshRequest:
      type: object
      properties:
        userId:
          type: string
          default: support@example.com
        refresh_token:
          type: string

    WebTokenRequest:
      description: User Id and password.
      type: object
      required:
        - userId
        - password
      properties:
        userId:
          type: string
          default: support@example.com
        password:
          type: string
          default: support
        newPassword:
          type: string
          default: support
        refreshToken:
          type: string
      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
        username:
          type: string
        created:
          type: integer
          format: int64
        userMustChangePassword:
          type: boolean
        errorCode:
          type: integer     # 0 = no error, 1 = passwordAlreadyUsed, 2=invalidPassword
        aclTemplate:
          $ref: '#/components/schemas/WebTokenAclTemplate'

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

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

    SubMfaConfig:
      type: object
      properties:
        id:
          type: string
          format: uuid
        type:
          type: string
          enum:
            - disabled
            - sms
            - email
        email:
          type: string
          format: email
        sms:
          type: string

    NoteInfo:
      type: object
      properties:
        created:
          type: integer
          format: int64
        createdBy:
          type: string
        note:
          type: string

    ObjectInfo:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        description:
          type: string
        notes:
          type: array
          items:
            $ref: '#/components/schemas/NoteInfo'
        created:
          type: integer
          format: int64
        modified:
          type: integer
          format: int64
        tags:
          type: array
          items:
            type: integer
            format: int64

    SignupEntry:
      type: object
      properties:
        allOf:
          $ref: '#/components/schemas/ObjectInfo'
        email:
          type: string
          format: email
        userId:
          type: string
          format: uuid
        macAddress:
          type: string
        serialNumber:
          type: string
        created:
          type: integer
          format: int64
        completed:
          type: integer
          format: int64
        error:
          type: integer
          format: int64
        status:
          type: string
        statusCode:
          type: integer
          format: int64

    StatsEntry:
      type: object
      properties:
        timestamp:
          type: integer
          format: int64
        tx:
          type: integer
          format: int64
        rx:
          type: integer
          format: int64

    StatsBlock:
      type: object
      properties:
        modified:
          type: integer
          format: int64
        external:
          type: array
          items:
            $ref: '#/components/schemas/StatsEntry'
        internal:
          type: array
          items:
            $ref: '#/components/schemas/StatsEntry'

    ExtraSystemConfiguration:
      type: array
      items:
        type: object
        properties:
          parameterName:
            type: string
          parameterValue:
            type: string

    #########################################################################################
    ##
    ## These are endpoints that all services in the OPenWiFI stack must provide
    ##
    #########################################################################################
    AnyPayload:
      type: object
      properties:
        Document:
          type: string

    StringList:
      type: object
      properties:
        list:
          type: array
          items:
            type: string

    TagValuePair:
      type: object
      properties:
        tag:
          type: string
        value:
          type: string

    TagValuePairList:
      type: object
      properties:
        tagList:
          type: array
          items:
            $ref: '#/components/schemas/TagValuePair'

    TagIntPair:
      type: object
      properties:
        tag:
          type: string
        value:
          type: integer
          format: int64

    TagIntPairList:
      type: object
      properties:
        tagList:
          type: array
          items:
            $ref: '#/components/schemas/TagIntPair'

    SystemCommandDetails:
      type: object
      properties:
        command:
          type: string
          enum:
            - setloglevels
            - getloglevels
            - getSubSystemNames
            - getLogLevelNames
            - stats
        parameters:
          oneOf:
            - $ref: '#/components/schemas/StringList'
            - $ref: '#/components/schemas/TagValuePairList'

    SystemCommandSetLogLevel:
      type: object
      properties:
        command:
          type: string
          enum:
            - setloglevel
        subsystems:
          type: array
          items:
            $ref: '#/components/schemas/TagValuePair'

    SystemCommandReload:
      type: object
      properties:
        command:
          type: string
          enum:
            - reload
        subsystems:
          type: array
          items:
            type: string
            example: these are the SubSystems names retrieve with the GetSubSystemsNamesResult.

    SystemCommandGetLogLevels:
      type: object
      properties:
        command:
          type: string
          enum:
            - getloglevels

    SystemGetLogLevelsResult:
      type: object
      properties:
        taglist:
          type: array
          items:
            $ref: '#/components/schemas/TagValuePair'

    SystemCommandGetLogLevelNames:
      type: object
      properties:
        command:
          type: string
          enum:
            - getloglevelnames

    SystemCommandGetSubsystemNames:
      type: object
      properties:
        command:
          type: string
          enum:
            - getsubsystemnames

    SystemCommandGetLogLevelNamesResult:
      type: object
      properties:
        list:
          type: array
          items:
            type: string

    SystemGetSubSystemNamesResult:
      type: object
      properties:
        taglist:
          type: array
          items:
            $ref: '#/components/schemas/TagValuePair'

    SystemInfoResults:
      type: object
      properties:
        version:
          type: string
        uptime:
          type: integer
          format: integer64
        start:
          type: integer
          format: integer64
        os:
          type: string
        processors:
          type: integer
        hostname:
          type: string
        certificates:
          type: array
          items:
            type: object
            properties:
              filename:
                type: string
              expires:
                type: integer
                format: int64

    SystemResources:
      type: object
      properties:
        numberOfFileDescriptors:
          type: integer
          format: int64
        currRealMem:
          type: integer
          format: int64
        peakRealMem:
          type: integer
          format: int64
        currVirtMem:
          type: integer
          format: int64
        peakVirtMem:
          type: integer
          format: int64

    SystemCommandResults:
      type: object
      oneOf:
        - $ref: '#/components/schemas/SystemResources'
        - $ref: '#/components/schemas/SystemInfoResults'
        - $ref: '#/components/schemas/StringList'
        - $ref: '#/components/schemas/TagValuePairList'

paths:
  /oauth2:
    post:
      tags:
        - Authentication
      summary: Get access token - to be used as Bearer token header for all other API requests.
      operationId: getAccessToken
      parameters:
        - in: query
          name: newPassword
          description: used when a user is trying to change her password. This will be the new password.
          schema:
            type: string
          required: false
        - in: query
          name: forgotPassword
          description: A user forgot her password. She needs to present her e-mail address in the userId and set this to true
          schema:
            type: boolean
          required: false
        - in: query
          name: requirements
          description: A user forgot her password. This will provided the password requirements.
          schema:
            type: boolean
          required: false
        - in: query
          name: resendMFACode
          schema:
            type: boolean
          required: false
        - in: query
          name: completeMFAChallenge
          schema:
            type: boolean
          required: false
        - in: query
          name: grant_type
          schema:
            type: string
            example: refresh_token
          required: false
      requestBody:
        description: User id and password
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/WebTokenRequest'
                - $ref: '#/components/schemas/MFAChallengeResponse'
                - $ref: '#/components/schemas/WebTokenRefreshRequest'
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/WebTokenResult'
                  - $ref: '#/components/schemas/MFAChallengeRequest'
        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:
        204:
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/responses/Success'
        403:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'

  /subscriber:
    get:
      tags:
        - Subscriber Information
      summary: Get the information about the subscriber
      operationId: getSubscriberInfo
      responses:
        200:
          $ref: '#/components/schemas/SubscriberInfo'
    put:
      tags:
        - Subscriber Information
      summary: Modify the information stored about the subscriber
      operationId: modifySubscriberInfo
      parameters:
        - in: query
          name: configChanged
          schema:
            type: boolean
            default: false
          required: false
        - in: query
          name: applyConfigOnly
          schema:
            type: boolean
            default: false
          required: false
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscriberInfo'
      responses:
        200:
          $ref: '#/components/schemas/SubscriberInfo'
        400:
          $ref: '#/components/responses/BadRequest'
    delete:
      tags:
        - Subscriber Information
      summary: Remove the subscriber from the DB
      operationId: deleteSubscriberInfo
      responses:
        200:
          $ref: '#/components/responses/Success'
        400:
          $ref: '#/components/responses/BadRequest'


  /wiredclients:
    get:
      tags:
        - Clients
      summary: Get the list of wired clients
      operationId: getWiredClients
      parameters:
        - in: query
          name: serialNumber
          schema:
            type: string
          required: true
      responses:
        200:
          description: Successfully retrieved client list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientList'

  /wificlients:
    get:
      tags:
        - WiFi Clients
      summary: Get the list of wired clients
      operationId: getWifiClients
      parameters:
        - in: query
          name: serialNumber
          schema:
            type: string
          required: true
      responses:
        200:
          description: Successfully retrieved client list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssociationList'

  /submfa:
    get:
      tags:
        - MFA
      summary: Retrieve the current setting for MFA
      operationId: getMFS
      responses:
        200:
          $ref: '#/components/schemas/SubMfaConfig'

    put:
      tags:
        - MFA
      summary: Retrieve the current setting for MFA
      operationId: modifyMFS
      parameters:
        - in: query
          name: startValidation
          schema:
            type: boolean
          required: false
        - in: query
          name: completeValidation
          schema:
            type: boolean
          required: false
        - in: query
          name: challengeCode
          schema:
            type: string
          required: false
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubMfaConfig'
      responses:
        200:
          $ref: '#/components/schemas/SubMfaConfig'
        400:
          $ref: '#/components/responses/BadRequest'

  /action:
    post:
      tags:
        - Device Commands
      summary: Sending different commands to a device
      operationId: performAnAction
      parameters:
        - in: query
          name: action
          schema:
            type: string
            enum:
              - reboot
              - blink
              - upgrade
              - factory
              - refresh
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                mac:
                  type: string
                when:
                  type: integer
                  format: int64
                duration:
                  type: integer
                  format: int64
                pattern:
                  type: string
                  enum:
                    - on
                    - off
                    - blink

      responses:
        200:
          $ref: '#/components/responses/Success'
        400:
          $ref: '#/components/responses/BadRequest'

  /signup:
    get:
      tags:
        - Subscriber Registration
      summary: This call allows someone to get the status of a signup.
      operationId: getSignup
      parameters:
        - in: query
          name: email
          schema:
            type: string
            format: email
          required: false
        - in: query
          name: macAddress
          schema:
            type: string
          required: false
        - in: query
          name: signupUUID
          schema:
            type: string
            format: uuid
          required: false
        - in: query
          name: dashboard
          schema:
            type: boolean
            default: false
          required: false
        - in: query
          name: deviceID
          schema:
            type: string
          required: false
      responses:
        200:
          $ref: '#/components/schemas/SignupEntry'
        400:
          $ref: '#/components/responses/BadRequest'
        403:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'

    delete:
      tags:
        - Subscriber Registration
      summary: This call allows someone to get the status of a signup.
      operationId: deleteSignup
      parameters:
        - in: query
          name: email
          schema:
            type: string
            format: email
          required: false
        - in: query
          name: macAddress
          schema:
            type: string
          required: false
        - in: query
          name: signupUUID
          schema:
            type: string
            format: uuid
          required: false
        - in: query
          name: deviceID
          schema:
            type: string
          required: false
      responses:
        204:
          $ref: '#/components/responses/Success'
        400:
          $ref: '#/components/responses/BadRequest'
        403:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'

    post:
      tags:
        - Subscriber Registration
      summary: This call allows a new subscriber to register themselves and their devices.
      operationId: postSignup
      parameters:
        - in: query
          name: email
          schema:
            type: string
            format: email
          required: true
        - in: query
          name: macAddress
          schema:
            type: string
          required: true
        - in: query
          name: deviceID
          schema:
            type: string
          required: false
        - in: query
          name: registrationId
          schema:
            type: string
          required: true
      responses:
        200:
          $ref: '#/components/schemas/SignupEntry'
        400:
          $ref: '#/components/responses/BadRequest'
        403:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'

    put:
      tags:
        - Subscriber Registration
      summary: modify the signup command in play
      operationId: modifySignup
      parameters:
        - in: query
          name: signupUUID
          schema:
            type: string
            format: uuid
          required: true
        - in: query
          name: operation
          schema:
            type: string
            enum:
              - cancel
              - success
              - inprogress
              - failed
              - poll
          required: true
        - in: query
          name: deviceID
          schema:
            type: string
          required: false
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                reason:
                  type: string
                time:
                  type: integer
                  format: int64
                errorCode:
                  type: integer
                  format: int32
                status:
                  type: string
        required: false

      responses:
        200:
          $ref: '#/components/schemas/SignupEntry'
        400:
          $ref: '#/components/responses/BadRequest'
        403:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'

  /stats/{mac}:
    get:
      tags:
        - Device Statistics
      summary: Get a list of statistics about the MAC address inout/output in terms of bytes
      operationId: getStats
      parameters:
        - in: path
          name: mac
          schema:
            type: string
          required: true
      responses:
        200:
          $ref: '#/components/schemas/StatsBlock'
        404:
          $ref: '#/components/responses/NotFound'

  /system:
    post:
      tags:
        - System Commands
      summary: Perform some system wide commands.
      operationId: systemCommand
      requestBody:
        description: Command details
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/SystemCommandSetLogLevel'
                - $ref: '#/components/schemas/SystemCommandReload'
                - $ref: '#/components/schemas/SystemCommandGetLogLevels'
                - $ref: '#/components/schemas/SystemCommandGetLogLevelNames'
                - $ref: '#/components/schemas/SystemCommandGetSubsystemNames'
      responses:
        200:
          description: Successful command execution
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/SystemGetLogLevelsResult'
                  - $ref: '#/components/schemas/SystemCommandGetLogLevelNamesResult'
                  - $ref: '#/components/schemas/SystemGetSubSystemNamesResult'
        403:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'
    get:
      tags:
        - System Commands
      summary: Retrieve different values from the running service.
      operationId: getSystemCommand
      parameters:
        - in: query
          description: Get a value
          name: command
          schema:
            type: string
            enum:
              - info
              - extraConfiguration
              - resources
          required: true
      responses:
        200:
          $ref: '#/components/schemas/SystemCommandResults'
        403:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'


  /systemConfiguration:
    get:
      tags:
        - SystemConfiguration
      summary: Retrieve system configuration items
      operationId: getSystemConfiguration
      parameters:
        - in: query
          description: Which parameters you want to retrieve
          name: entries
          schema:
            type: string
            example:
              - element1
              - element1,element2,element3
          required: false
      responses:
        200:
          description: List of configuration elements
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ExtraSystemConfiguration'
        403:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'

    put:
      tags:
        - SystemConfiguration
      summary: Set some or all system configuration
      operationId: setSystemConfiguration
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExtraSystemConfiguration'

      responses:
        200:
          $ref: '#/components/schemas/ExtraSystemConfiguration'
        403:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'

    delete:
      tags:
        - SystemConfiguration
      summary: Delete all additional system configuration
      operationId: deleteSystemConfiguration

      responses:
        200:
          $ref: '#/components/responses/Success'
        403:
          $ref: '#/components/responses/Unauthorized'
        404:
          $ref: '#/components/responses/NotFound'