openapi: 3.0.0
info:
  title: Application Enablement Platform
  version: R2.1
  # 0.1.2
  description: |
      ![Shabodi](https://shabodi-ws.b-cdn.net/wp-content/uploads/2023/07/Group-88453.png)
      ## **Overview**

      Shabodi NetAware enables applications to become network aware by providing access to previously inaccessible network functionalities through user-friendly APIs. These APIs are categorized into two main groups: administrative and service APIs. Service APIs harness the intelligence of NetAwares orchestration capabilities and near-real-time engine to dynamically shape the network and obtain valuable insights into its operation.  The NetAware also solves a multitude of use cases where many types of networks and vendors are involved in the application and orchestration is required to achieve overall management and quality throughout.

      ![NetAware Overview](https://i.postimg.cc/L6fwz6fs/tmp-585cd389-bbde-4f95-afc5-ae56c7ce62d6.png)

      This document serves as a comprehensive reference guide, offering visibility into both the administrative and service APIs provided by NetAware. It provides detailed information regarding the features accessible to applications and describes the parameters necessary to invoke them effectively from your application.
      
      In NetAware release 2.1 simplified service APIs provides an application the ability to:
      * Configure **quality of service** for a device
        - __Bandwidth__
          - set uplink and downlink maximum bit rate
        - __Latency__
        - __Jitter__
      * Retrieve center point __location__ of a device
      * Retrieve device __insights__ such as device status and event notifications 
        - In this version, the only event type supported is **'connectivity'** which refers to the network connectivity status of a device.
      
      ### **Applications**
      
      In the context of networks, an application (or application function) refers to the specific purpose or task that a use case is designed to perform. Both wireless and wired networks support various applications, ranging from simple messaging and email services to more complex multimedia streaming, gaming, and location-based services.

      Application functions are designed to meet the requirements and preferences of users or devices, as well as to leverage the capabilities and limitations of the underlying infrastructure. They play a crucial role in enabling various use cases in commercial settings such as drones, AGVs, robotics, surveillance object detection and more.

      A network aware application leverages Shabodi's APIs to gain insights and control the network for connected devices for which it is managing.

      For provisining, use **Application Registration** APIs below to bind new application to your NetAware . Note that application registration is a two step process:``pre-onboarding``and``onboarding``must be performed.

      <center><img border="0" src="https://i.postimg.cc/d1BNSwby/image-2.png" alt="Network Aware Application" width="500" height="470"></a></center>

      ### **Relevant Terms and Definitions**

        | Term              |     Definition                                                                                                                                             |
        |-------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------
        | **SNBP**           |Shabodi Northbound Platform responsible for registration, authentication, management and API discovery.|
        | **Invoker**       |Application function invoking APIs to API providers.|
        | **Provider**       |Services or applications publishing capabilities to application functions.|
        | **QoS**            |Quality of Service – programmability of the network to dynamically adapt and allocate resources to meet the quality requirements of different services or applications in real-time.|
        | **Insights**      |Insights provide a window into the networks managed by NetAware , enabling applications and devices to dynamically adapt to their evolving environment. |
        | **Admin APIs**    |Set of APIs to manage applications, registration and services offered by SNBP.|
        | **Service APIs**  |Set of APIs to expose network functions to applications, including QoS, Location and Insights. |
        | **MBR**           |Maximum Bit Rate defines the maximum bit rate being allocated to a device or group of devices. MBR is particularly useful to cap bandwidth for devices that are resource intensive or noisy.|
        | **GBR**           |Guaranteed Bit Rate defines the minimum bit rate allocation to a device or group of devices. Useful in situations where a device has high bandwidth demands and needs to maintain a high quality of service. |
        | **Downlink**      |Downlink describes a link direction from network towards device. |
        | **Uplink**        |Uplink describes a link direction from device towards network. |
        | **Subscription**  |Refers to the ability to subsribe to event notification from NetAware  based on specific topics. |
        | **Sandbox**       |Shabodi hosted NetAware  used for API testing, proof of concepts and early integration of new APIs. |

      ## **Pre-Requisites**

      ### **Networks**

      A networks refers to interconnected systems that facilitates communication and data exchange, utilizing advanced infrastructure such as routers, controllers and radio access equipment, like RANs or access points.  Shabodi's NetAware  accomodates many network types such as 4G, 5G, WiFi and SD-WAN.

      A network comprises interconnected systems designed to facilitate communication and data exchange. It utilizes advanced infrastructure components such as routers, controllers, and radio access equipment like RANs or access points. Shabodi's NetAware  (Application Enablement Platform) accommodates various network types including 4G, 5G, WiFi, and SD-WAN.

      Configuring network information on the NetAware  is essential to ensure that applications and devices operate seamlessly in alignment with the services provided by the NetAware . **For configuring networks on NetAware  - please refer to the **Networks** section of **User administration guide.**
      

      ### **Devices**

      In the context of advanced networks, a device refers to any hardware component that can connect to the network, typically using protocols such as Wi-Fi  or cellular. Devices can include cameras, drones, autonomous ground vehicles (AGV), vehicles, smart protective equipment, and many others.

      These devices communicate with each other and with network infrastructure such as routers, access points, and cellular towers to access data, services, and resources available on the network or the internet. They typically have built-in wireless network interfaces that enable them to send and receive data wirelessly, allowing users to stay connected and access information or services from anywhere within the network coverage area.

      A network aware application has the ability to understand and control the data path to your devices so that reliability and overall fidelity of the experience is maintained.  Devices need to first be configured on the NetAware  so that then can be managed by applications - please refer to the **Devices** section of **user administration guide** on how to add and map devices to your applications.

      ## **Using NetAware  APIs** 
      
      ### **Authentication**

      The NetAware  supports OAuth2.0 which is the industry standard protocol for authentication. OAuth2.0 leverages the use of authentication bearer tokens – these are strings that OAuth clients use to make requests to the resource server.

      ### **Headers**

      The following headers are required to invoke json based request into NetAware .

        * ``Content-Type: application/json``
        * ``Authorization: Bearer <access_token>``

      ### **Path Templating**

      Path templating refers to the usage of template expressions, delimited by curly braces ({}), to mark a section of a URL path as replaceable using path parameters.
      Each template expression in the path MUST correspond to a path parameter that is included in the Path Item itself and/or in each of the Path Item’s Operations.  The value for these path parameters MUST NOT contain any unescaped “generic syntax” characters described by [RFC3986]: forward slashes (/), question marks (?), or hashes (#)

      ### **Error Codes**

      All HTTP response status codes are separated into categories. The first digit of the status code defines the class of response, while the last two digits do not have any classifying or categorization role. The NetAware  focuses primarily on three classes of error codes:
        *  ``2xx`` successful – the request was successfully received, understood, and accepted
        *  ``4xx`` client error – the request contains bad syntax or cannot be fulfilled
        *  ``5xx`` server error – the server failed to fulfil an apparently valid request

      **Notes:** 
        * In cases where the NetAware  is unable to orchestrate the requested operation for a specified device, a``422 - Unprocessable``error code is returned.
        * When the API being invoked falls outside the scope of the purchased license a``403 - Permission Denied``error code is returned.

      ### **Defaults**

      For consistency, APIs only use``kbps``when refering to bit rates and``ms``when refering to time and duration. 
      
      The date-time format used refers to the date-time notation defined by RFC 3339, section 5.6. DateTimeOffset values are expressed as in the format ``yyyy-mm-ddThh:mm[:ss[.fff]]zzzz``. For example,``2023-02-08T18:04:28Z``.  
         * The offset component is expressed in the format +|-hh:mm. For example, +12:00 or -09:30.
         * The hours component must be specified as two digits in 24-hour format.
         * When used in filter queries, the :ss seconds and .fff fractional seconds components are optional and may be expressed up to 3 decimal places of precision.

        For example, the date 30 Dec 2001 9:30:00AM +1200 is formatted as 2001-12-30T09:30:00+12:00.
      
      ### **Hosts and Ports**

      Shabodi’s NetAware  is deployed with a microservices based model which means a service port is required when invoking requests in the following format.
      ``http://{NetAware _HOST}:{SERVICE_PORT}``
        *  NetAware _HOST address is the IP address of the virtual machine hosting the NetAware  application.
        *  Admin APIs are accessible through port``8561``
        *  Service APIs are accessible through port``7999``

      ### **Event Subscriptions**

      For some network types, NetAware  offers the abiity for applications to subscribe to insightful network events. Currently, the NetAware  supports two event types, called **topics**:
        * ```connectivity```       Connectivity events will notify the application of a device connectivity state change. For example, if a device is disconnected from the network, a disconnected event for that device will be sent to application.
        * ```deviceUtilization```  deviceUtilization events can be triggered based on active GBR sessions. Device utilization is measured as (current device utilization)/(guaranteed bit rate). The percent value represents the amount of allocated bandwidth being used for a device. A max and min threshold can be configured to trigger the event. For example, if my device reaches 90% of its guaranteed bit rate allocation, notify the application.  The application can then use these insights to allocate more bandwidth as required to maintain device performance.

      **Filters** can also be configured per subscription in order to define a scope or set of devices for the event notification.  For example, if I want to subscribe to an event notification for only one device (device 2, in network 1), I can define this by adding a filter *"net1.device2"*. Similarly, if I want to subscribe to event notifications for all devices in network 1, I can use a wildcard (\*) such as "net1.\*"

      Reminder that device and network identifiers can be found in the``device.json`` and ``network.json`` files respectively. Refer to the **user administration guide** for more details.

      ### **Sandbox**

      Shabodi offers developers a playground to test and integrate their applications with NetAware s APIs.  This environment can be made available to customers or developers on a per request basis. Contact support@shabodi.com to request access.


  contact:
    email: developer.support@shabodi.com
externalDocs:
  description: Product documentation available
  url: https://learn.shabodi.com/login/

servers:
  - url: "{apiRoot}/"
    variables:
      apiRoot:
        default: http://{NetAware _HOST}:31001|31002
        description: API root

tags:
  - name: Application Registration 
    description: Granting of permissions is required by NetAware  for applications to access its services and features.  There are two steps in this process, pre-onboarding, and onboarding of the application. 
  - name: Token Generation
    description: Acquiring an OAuth2 token for invoking service APIs
  - name: Quality of Service
    description: Operations to configure  quality of service parameters for a device
  - name: Location
    description: Obtain device location with a center point
  - name: Insights
    description: Receive insights with event based subscriptions    
 
paths:

  /api-invoker-management/v1/preOnboardedInvokers:
    post:
      tags:
        - Application Registration
      summary: "Pre-onboard an application"
      operationId: preOnboard
      requestBody:
        description: |
                Provide a name and description for the application being pre-onboarded
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PreOnboard"
      responses:
        "201":
          description: Response provides a Bearer token that is required for application onboarding
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PreOnboardResponse"
        "400":
          description: Invalid input for pre-onboard operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorInfo"
              examples:
                Generic400:
                  summary: Some parameter combinations or parameter values provided are not schema compliant
                  value:
                    status: 400
                    code: INVALID_ARGUMENT
                    message: "Schema validation failed at  ..."
        "401":
          $ref: "#/components/responses/Generic401"
        "403":
          $ref: "#/components/responses/Generic403"
        "409":
          description: Conflict
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorInfo"
              example:
                status: 409
                code: CONFLICT
                message: "Another application is already pre-onboarded with this name"
        "422":
          description: Unprocessable
          $ref: "#/components/responses/Generic422"
        "500":
          $ref: "#/components/responses/Generic500"
        "503":
          $ref: "#/components/responses/Generic503"

  /api-invoker-management/v1/onboardedInvokers:
    post:
      tags:
        - Application Registration
      summary: "Onboard an application"
      operationId: Onboard
      requestBody:
        description: |
                Provide pre-onboarded token as input Bearer token in this Post request
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Onboard"
      responses:
        "201":
          description: Response provides information regarding newly onboarded application
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OnboardResponse"
        "400":
          description: Invalid input for pre-onboard operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorInfo"
              examples:
                Generic400:
                  summary: Some parameter combinations or parameter values provided are not schema compliant
                  value:
                    status: 400
                    code: INVALID_ARGUMENT
                    message: "Schema validation failed at  ..."
        "401":
          $ref: "#/components/responses/Generic401"
        "403":
          $ref: "#/components/responses/Generic403"
        "409":
          description: Conflict
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorInfo"
              example:
                status: 409
                code: CONFLICT
                message: "Another application is already pre-onboarded with this name"
        "422":
          description: Unprocessable
          $ref: "#/components/responses/Generic422"
        "500":
          $ref: "#/components/responses/Generic500"
        "503":
          $ref: "#/components/responses/Generic503"
    get:
      tags:
        - Application Registration
      summary: "Retrieve information for all onboarded applications"
      operationId: getOnboard
      responses:
        "200":
          description: Response provides an array of onboarded applications
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GetOnboardResponse"
        "400":
          description: Invalid input for onboard operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorInfo"
              examples:
                Generic400:
                  summary: Some parameter combinations or parameter values provided are not schema compliant
                  value:
                    status: 400
                    code: INVALID_ARGUMENT
                    message: "Schema validation failed at  ..."
        "401":
          $ref: "#/components/responses/Generic401"
        "403":
          $ref: "#/components/responses/Generic403"
        "409":
          description: Conflict
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorInfo"
              example:
                status: 409
                code: CONFLICT
                message: "Another application is already pre-onboarded with this name"
        "422":
          description: Unprocessable
          $ref: "#/components/responses/Generic422"
        "500":
          $ref: "#/components/responses/Generic500"
        "503":
          $ref: "#/components/responses/Generic503"

  /api-invoker-management/v1/onboardedInvokers/{appId}:
    put:
      tags:
        - Application Registration
      summary: "Update an onboarded application"
      operationId: appUpdate
      parameters:
        - name: appId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        description: |
                Update information of an onboarded application
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateAppRequest"
      responses:
        "200":
          description: Response provides transactionId and remaining time of the bandwidth session
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UpdateAppResponse"
        "400":
          description: Invalid input for pre-onboard operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorInfo"
              examples:
                Generic400:
                  summary: Some parameter combinations or parameter values provided are not schema compliant
                  value:
                    status: 400
                    code: INVALID_ARGUMENT
                    message: "Schema validation failed at  ..."
        "401":
          $ref: "#/components/responses/Generic401"
        "403":
          $ref: "#/components/responses/Generic403"
        "409":
          description: Conflict
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorInfo"
              example:
                status: 409
                code: CONFLICT
                message: "Another application is already pre-onboarded with this name"
        "422":
          description: Unprocessable
          $ref: "#/components/responses/Generic422"
        "500":
          $ref: "#/components/responses/Generic500"
        "503":
          $ref: "#/components/responses/Generic503"

    delete:
      tags:
        - Application Registration
      summary: "Delete an onboarded application"
      operationId: appDelete
      parameters:
        - name: appId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Application removed
        "400":
          description: Invalid input for pre-onboard operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorInfo"
              examples:
                Generic400:
                  summary: Some parameter combinations or parameter values provided are not schema compliant
                  value:
                    status: 400
                    code: INVALID_ARGUMENT
                    message: "Schema validation failed at  ..."
        "401":
          $ref: "#/components/responses/Generic401"
        "403":
          $ref: "#/components/responses/Generic403"
        "409":
          description: Conflict
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorInfo"
              example:
                status: 409
                code: CONFLICT
                message: "Another application is already pre-onboarded with this name"
        "422":
          description: Unprocessable
          $ref: "#/components/responses/Generic422"
        "500":
          $ref: "#/components/responses/Generic500"
        "503":
          $ref: "#/components/responses/Generic503"      

  /security/v1/token:
    post:
      tags:
        - Token Generation
      summary: "Acquire an access token"
      operationId: getToken
      requestBody:
        description: Acquire an access token to invoke a service API
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/GetToken"
      responses:
        "200":
          description: Access token acquired
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GetTokenResponse"
        "400":
          description: Invalid input for pre-onboard operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorInfo"
              examples:
                Generic400:
                  summary: Some parameter combinations or parameter values provided are not schema compliant
                  value:
                    status: 400
                    code: INVALID_ARGUMENT
                    message: "Schema validation failed at  ..."
        "403":
          $ref: "#/components/responses/Generic403"
        "500":
          $ref: "#/components/responses/Generic500"
        "503":
          $ref: "#/components/responses/Generic503"      

  /qos/v1/bandwidth:
    post:
      tags:
        - Quality of Service
      summary: "Set uplink or downlink maximum bitrate for a device"
      operationId: setBandwidth
      requestBody:
        description: |
                Bandwidth quality of service for the specified device - either maxBitRate (MBR) or guranteedBitRate (GBR) should be provided
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SetBandwidth"
      responses:
        "201":
          description: Response provides transactionId, start end expiry time of the bandwidth session
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SetBandwidthResponse"
        "400":
          description: Invalid input for bandwidth operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorInfo"
              examples:
                Generic400:
                  summary: Some parameter combinations or parameter values provided are not schema compliant
                  value:
                    status: 400
                    code: INVALID_ARGUMENT
                    message: "Schema validation failed at  ..."
                DeviceMissing:
                  summary: Device must be specified
                  value:
                    status: 400
                    code: INVALID_ARGUMENT
                    message: "Expected property is missing: device"
                InsufficientDeviceProperties:
                  summary: Device must be identified by at least one parameter
                  value:
                    status: 400
                    code: INVALID_ARGUMENT
                    message: "Insufficient properties specified: device"
                InconsistentDeviceProperties:
                  summary: Device parameters provided identify different devices
                  value:
                    status: 400
                    code: INVALID_ARGUMENT
                    message: "Multiple inconsistent parameters specified: device"
                CannotIdentifyDevice:
                  summary: No device can be identified from provided parameters
                  value:
                    status: 400
                    code: INVALID_ARGUMENT
                    message: "Unable to identify device from specified parameters: device"
                bitrateMissing:
                  summary: maxBitRate or guaranteedBitRate must be specified
                  value:
                    status: 400
                    code: INVALID_ARGUMENT
                    message: "Expected property is missing: maxBitRate or guaranteedBitRate"
        "401":
          $ref: "#/components/responses/Generic401"
        "403":
          $ref: "#/components/responses/Generic403"
        "409":
          description: Conflict
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorInfo"
              example:
                status: 409
                code: CONFLICT
                message: "Another bandwidth session is alraedy created for the same device - must DELETE first"
        "422":
          description: Unprocessable
          $ref: "#/components/responses/Generic422"
        "500":
          $ref: "#/components/responses/Generic500"
        "503":
          $ref: "#/components/responses/Generic503"
    get:
      tags:
        - Quality of Service
      summary: "Retrieve active bandwidth sessions"
      parameters:
        - name: deviceId
          in: query
          schema:
            type: integer
          required: false
      responses:
        "200":
          description: Example Response returns array of bandwidth sessions unless deviceId is provided as query parameter
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GetBandwidthResponse"
        "400":
          $ref: "#/components/responses/Generic400"
        "401":
          $ref: "#/components/responses/Generic401"
        "403":
          $ref: "#/components/responses/Generic403"
        "404":
          $ref: "#/components/responses/Generic404"
        "500":
          $ref: "#/components/responses/Generic500"
        "503":
          $ref: "#/components/responses/Generic503"

  /qos/v1/bandwidth/{deviceId}:
    delete:
      tags:
        - Quality of Service
      summary: "End an active bandwidth session for a device"
      parameters:
        - name: deviceId
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Successful operation
        "400":
          $ref: "#/components/responses/Generic400"
        "401":
          $ref: "#/components/responses/Generic401"
        "403":
          $ref: "#/components/responses/Generic403"
        "404":
          $ref: "#/components/responses/SessionNotFound404"
        "500":
          $ref: "#/components/responses/Generic500"
        "503":
          $ref: "#/components/responses/Generic503"
  /qos/v1/latency:
    post:
      tags:
        - Quality of Service
      summary: "Set latency for a device"
      requestBody:
        description: |
                Latency quality of service for the specified device
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SetLatency"
      responses:
        "201":
          description: Response provides transactionId, start end expiry time of the bandwidth session
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SetLatencyResponse"
        "400":
          description: Invalid input for latency operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorInfo"
              examples:
                Generic400:
                  summary: Some parameter combinations or parameter values provided are not schema compliant
                  value:
                    status: 400
                    code: INVALID_ARGUMENT
                    message: "Schema validation failed at  ..."
                DeviceMissing:
                  summary: Device must be specified
                  value:
                    status: 400
                    code: INVALID_ARGUMENT
                    message: "Expected property is missing: device"
                InsufficientDeviceProperties:
                  summary: Device must be identified by at least one parameter
                  value:
                    status: 400
                    code: INVALID_ARGUMENT
                    message: "Insufficient properties specified: device"
                InconsistentDeviceProperties:
                  summary: Device parameters provided identify different devices
                  value:
                    status: 400
                    code: INVALID_ARGUMENT
                    message: "Multiple inconsistent parameters specified: device"
                CannotIdentifyDevice:
                  summary: No device can be identified from provided parameters
                  value:
                    status: 400
                    code: INVALID_ARGUMENT
                    message: "Unable to identify device from specified parameters: device"
                latencyMissing:
                  summary: Latency must be specified
                  value:
                    status: 400
                    code: INVALID_ARGUMENT
                    message: "Expected property is missing: latency"
        "401":
          $ref: "#/components/responses/Generic401"
        "403":
          $ref: "#/components/responses/Generic403"
        "409":
          description: Conflict
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorInfo"
              example:
                status: 409
                code: CONFLICT
                message: "Another latency session is alraedy created for the same device - must DELETE first"
        "422":
          $ref: "#/components/responses/Generic422"
        "500":
          $ref: "#/components/responses/Generic500"
        "503":
          $ref: "#/components/responses/Generic503"
    get:
      tags:
        - Quality of Service
      summary: "Retrieve active latency sessions"
      parameters:
        - name: deviceId
          in: query
          schema:
            type: integer
          required: true
      responses:
        "200":
          description: Example Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GetLatencyResponse"
        "400":
          $ref: "#/components/responses/Generic400"
        "401":
          $ref: "#/components/responses/Generic401"
        "403":
          $ref: "#/components/responses/Generic403"
        "404":
          $ref: "#/components/responses/Generic404"
        "500":
          $ref: "#/components/responses/Generic500"
        "503":
          $ref: "#/components/responses/Generic503"
  /qos/v1/latency/{deviceId}:
    delete:
      tags:
        - Quality of Service
      summary: "End an active latency session for a device"
      parameters:
        - name: deviceId
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Successful 
        "400":
          $ref: "#/components/responses/Generic400"
        "401":
          $ref: "#/components/responses/Generic401"
        "403":
          $ref: "#/components/responses/Generic403"
        "404":
          $ref: "#/components/responses/SessionNotFound404"
        "500":
          $ref: "#/components/responses/Generic500"
        "503":
          $ref: "#/components/responses/Generic503"
  /qos/v1/jitter:
    post:
      tags:
        - Quality of Service
      summary: "Set jitter for a device"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SetJitter"
      responses:
        "201":
          description: Example Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SetJitterResponse"
        "400":
          description: Invalid input for jitter operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorInfo"
              examples:
                Generic400:
                  summary: Some parameter combinations or parameter values provided are not schema compliant
                  value:
                    status: 400
                    code: INVALID_ARGUMENT
                    message: "Schema validation failed at  ..."
                DeviceMissing:
                  summary: Device must be specified
                  value:
                    status: 400
                    code: INVALID_ARGUMENT
                    message: "Expected property is missing: device"
                InsufficientDeviceProperties:
                  summary: Device must be identified by at least one parameter
                  value:
                    status: 400
                    code: INVALID_ARGUMENT
                    message: "Insufficient properties specified: device"
                InconsistentDeviceProperties:
                  summary: Device parameters provided identify different devices
                  value:
                    status: 400
                    code: INVALID_ARGUMENT
                    message: "Multiple inconsistent parameters specified: device"
                CannotIdentifyDevice:
                  summary: No device can be identified from provided parameters
                  value:
                    status: 400
                    code: INVALID_ARGUMENT
                    message: "Unable to identify device from specified parameters: device"
                jitterMissing:
                  summary: Jitter must be specified
                  value:
                    status: 400
                    code: INVALID_ARGUMENT
                    message: "Expected property is missing: jitter"
        "401":
          $ref: "#/components/responses/Generic401"
        "403":
          $ref: "#/components/responses/Generic403"
        "409":
          description: Conflict
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorInfo"
              example:
                status: 409
                code: CONFLICT
                message: "Another jitter session is alraedy created for the same device - must DELETE first"
        "422":
          $ref: "#/components/responses/Generic422"
        "500":
          $ref: "#/components/responses/Generic500"
        "503":
          $ref: "#/components/responses/Generic503"
    get:
      tags:
        - Quality of Service
      summary: "Retrieve active jitter sessions"
      parameters:
        - name: deviceId
          in: query
          schema:
            type: integer
          required: true
      responses:
        "200":
          description: Example Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GetJitterResponse"
        "400":
          $ref: "#/components/responses/Generic400"
        "401":
          $ref: "#/components/responses/Generic401"
        "403":
          $ref: "#/components/responses/Generic403"
        "404":
          $ref: "#/components/responses/Generic404"
        "500":
          $ref: "#/components/responses/Generic500"
        "503":
          $ref: "#/components/responses/Generic503"
  /qos/v1/jitter/{deviceId}:  
    delete:
      tags:
        - Quality of Service
      summary: "End an active jitter session for a device"
      parameters:
        - name: deviceId
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Successful operation
        "400":
          $ref: "#/components/responses/Generic400"
        "401":
          $ref: "#/components/responses/Generic401"
        "403":
          $ref: "#/components/responses/Generic403"
        "404":
          $ref: "#/components/responses/SessionNotFound404"
        "500":
          $ref: "#/components/responses/Generic500"
        "503":
          $ref: "#/components/responses/Generic503"
  /location/v1/center:
    get:
      tags:
        - Location
      summary: "Retrieve longitude and latitude location of a device"
      parameters:
        - name: deviceId
          in: query
          schema:
            type: integer
          required: true
      responses:
        '200':
          description: Latitude and longitude of a specified device based on a center point.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GetLocationResponse"
        "400":
          $ref: "#/components/responses/Generic400"
        "401":
          $ref: "#/components/responses/Generic401"
        "403":
          $ref: "#/components/responses/Generic403"
        "404":
          $ref: "#/components/responses/Generic404"
        "422":
          $ref: "#/components/responses/Generic422"
        "500":
          $ref: "#/components/responses/Generic500"
        "503":
          $ref: "#/components/responses/Generic503"


  /insights/v1/subscriptions:
    post:
      tags:
        - Insights
      summary: "Create an event based subscription for notifications"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateSubscription"
      callbacks:
        notifications:
          "{$request.body#/webhook/notificationUrl}":
            post:
              tags:
                - Session notifications callback
              summary: "Session notifications callback"
              description: |
                Important: this endpoint is to be implemented by the API consumer.
                The Device status server will call this endpoint whenever any device status related event occurs.
              operationId: postNotification
              requestBody:
                required: true
                content:
                  application/cloudevents+json:
                    schema:
                      $ref: "#/components/schemas/CreateCallback"
              responses:
                "204":
                  description: Successful notification
                "400":
                  $ref: "#/components/responses/Generic400"
                "401":
                  $ref: "#/components/responses/Generic401"
                "403":
                  $ref: "#/components/responses/Generic403"
                "422":
                  $ref: "#/components/responses/Generic422"
                "500":
                  $ref: "#/components/responses/Generic500"
                "503":
                  $ref: "#/components/responses/Generic503"
              security:
                - {}
                - notificationsBearerAuth: []
      responses:
        '201':
          description: Example Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreateSubscriptionResponse"
        "400":
          description: Invalid input for subscription operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorInfo"
              examples:
                Generic400:
                  summary: Some parameter combinations or parameter values provided are not schema compliant
                  value:
                    status: 400
                    code: INVALID_ARGUMENT
                    message: "Schema validation failed at  ..."
                TopicMissing:
                  summary: Topic must be specified
                  value:
                    status: 400
                    code: INVALID_ARGUMENT
                    message: "Expected property is missing: topic"
                NotificationMissing:
                  summary: Notification information must be specified
                  value:
                    status: 400
                    code: INVALID_ARGUMENT
                    message: "Insufficient properties specified: notification"
        "401":
          $ref: "#/components/responses/Generic401"
        "403":
          $ref: "#/components/responses/Generic403"
        "409":
          description: Conflict
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorInfo"
              example:
                status: 409
                code: CONFLICT
                message: "Another subscription is already created with specified filters"
        "422":
          $ref: "#/components/responses/Generic422"
        "500":
          $ref: "#/components/responses/Generic500"
        "503":
          $ref: "#/components/responses/Generic503"
        
    get:
      tags:
        - Insights
      summary: "Retrieve all active subscriptions"
      responses:
        '200':
          description: Example Response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GetSubscriptionResponse"
        "400":
          $ref: "#/components/responses/Generic400"
        "401":
          $ref: "#/components/responses/Generic401"
        "403":
          $ref: "#/components/responses/Generic403"
        "404":
          $ref: "#/components/responses/Generic404"
        "500":
          $ref: "#/components/responses/Generic500"
        "503":
          $ref: "#/components/responses/Generic503"
      
  /insights/v1/subscriptions/{subscriptionId}:
    get:
      tags:
        - Insights
      summary: "Retrieve details of an active subscriptions"
      parameters:
        - name: subscriptionId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Example Response
          content:
            application/json:
              schema:
                 $ref: "#/components/schemas/SubscriptionDetails"
        "400":
          $ref: "#/components/responses/Generic400"
        "401":
          $ref: "#/components/responses/Generic401"
        "403":
          $ref: "#/components/responses/Generic403"
        "404":
          $ref: "#/components/responses/SubscriptionNotFound404"
        "500":
          $ref: "#/components/responses/Generic500"
        "503":
          $ref: "#/components/responses/Generic503"
    delete:
      tags:
        - Insights
      summary: "Delete a subscription"
      parameters:
        - name: subscriptionId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful operation
        "400":
          $ref: "#/components/responses/Generic400"
        "401":
          $ref: "#/components/responses/Generic401"
        "403":
          $ref: "#/components/responses/Generic403"
        "404":
          $ref: "#/components/responses/SubscriptionNotFound404"
        "500":
          $ref: "#/components/responses/Generic500"
        "503":
          $ref: "#/components/responses/Generic503"
          
components:

  securitySchemes:
    openId:
      type: openIdConnect
      openIdConnectUrl: https://example.com/.well-known/openid-configuration
  schemas:

    PreOnboard:
      description: Application pre-onboarding details
      type: object
      properties:
        name: 
          description: Provide a name for the application
          type: string
          example: Drone Application
      required:
        - name

    PreOnboardResponse:
      type: object
      properties:
        name: 
          type: string
          example: Drone Application
        description:
          type: string
          example: Drone controller application for QoD
        ott:
          description: One-time token used for onboarding
          type: object
          properties:
            access_token:
              type: string
              example: eyJraWQiOiIxZGM5OTVhYi1iYWQxLTQ3ODgtODMxZC01MTA4ZTk2OGY2NTEiLCJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJTaGFib2RpIExBQVMiLCJhdWQiOiJTaGFib2RpIEFFUCIsInN1YiI6IjE3ZDAxYWExLThkY2QtNGQ3Yi05Y2FjLWZjNDMwNDY5OTQ5ZiIsInByZWZlcnJlZF91c2VybmFtZSI6IlNOQlAgREVNTyBBUFBMSUNBVElPTjYiLCJzY29wZSI6Im5iLmFwcC5jIiwiaWF0IjoxNzA5OTE4Nzg5LCJleHAiOjE3MTA1MjM1ODksImp0aSI6IjI2NDFiMWYwLTY1NzEtNDQ0Ny1iYjRkLWZlM2VhMjM5ZWVkOCJ9.LwSrSxJ_HsPn1msUGDzLiEOHMDM4Qia0hfnV5-GhuwE
            expires_in:
              description: Onboarding token expiry, in milliseconds
              type: integer
              example: 604800
            scope:
              type: string
              example: nb.app.c
            token_type:
              type: string
              example: bearer

    Onboard:
      type: object
      properties:
        notificationDestination:
          description: SNBP has ability to send notifications for application registrations. Provide a notification destination. 
          type: string
          example: https://a43f8337-033e-4b45-9afe-df121b62f95c.mock.pstmn.io/notifications
        requestTestNotification:
          description: true to enable application based notificaitons. 
          type: boolean
          example: true
        direction:
          description: Direction of link, either uplink or downlink. Used as a default when invoking quality of service APIs. Can be changed.
          type: string
          example: DL 
          enum:
            - UL
            - DL
        traffic:
          description: Traffic type, TCP is common selection.
          type: string
          example: TCP
          enum:
            - TCP
            - UDP
            - SCP
        ipv4: 
          description: IP address of the application being onboarded
          type: string
          example: 172.56.105.26
        description:
          description: Provide a description for the application
          type: string
          example: Drone controller application for QoD
        port: 
          description: Port of the application being onboarded
          type: integer
          example: 5559
      required:
        - notificationDestination
        - requestTestNotification
        - direction
        - traffic
        - ipv4
        - port
        - description
        
    OnboardResponse:
      type: object
      properties:
        apiInvokerId:
          type: string
          example: 17d01aa1-8dcd-4d7b-9cac-fc430469949f
        onboardingInformation:
          type: object
          properties:
            onboardingSecret:
              type: string
              example: eok9rStqticMq8yQiueKRYvB2raBoC13
        notificationDestination:
          type: string
          example: https://a43f8337-033e-4b45-9afe-df121b62f95c.mock.pstmn.io/notifications
        requestTestNotification:
          type: boolean
          example: true
        ipv4:
          description: IP address of the application
          type: string
          example: 172.56.105.26
        port: 
          description: Port of the application
          type: integer
          example: 5559
        direction:
          type: string
          example: DL 
        traffic:
          type: string
          example: TCP

    GetOnboardResponse:
      type: array
      items:
        properties:
          apiInvokerId:
            type: string
            example: 17d01aa1-8dcd-4d7b-9cac-fc430469949f
          onboardingInformation:
            type: object
            properties:
              onboardingSecret:
                type: string
                example: eok9rStqticMq8yQiueKRYvB2raBoC13
          notificationDestination:
            type: string
            example: https://a43f8337-033e-4b45-9afe-df121b62f95c.mock.pstmn.io/notifications
          requestTestNotification:
            type: boolean
            example: true
          description:
            type: string
            example: This is a demo application
          name:
            description: Friendly name of the application
            type: string
            example: Drone Application
          ipv4:
            description: IP address of the application
            type: string
            example: 172.56.105.26
          port: 
            description: Port of the application
            type: integer
            example: 5559
          direction:
            description: Application type, either uplink or downlink
            type: string
            example: DL 
          traffic:
            type: string
            example: TCP

    UpdateAppRequest:
      type: object
      properties:
        notificationDestination:
          type: string
          example: http://example.com/invoker/notification
        description:
          type: string
          example: This is a demo application

    UpdateAppResponse:
      type: object
      properties:
        apiInvokerId:
          type: string
          example: 17d01aa1-8dcd-4d7b-9cac-fc430469949f
        notificationDestination:
          type: string
          example: http://example.com/invoker/notification
        requestTestNotification:
          type: boolean
          example: true
        description:
          type: string
          example: This is a demo application

    GetToken:
      type: object
      properties:
        client_id:
          type: string
          example: 93f2c879-c3f9-4f51-9d74-2c84cc8081dd
        client_secret:
          type: string
          example: Ayd9zF8tGjcb63mK54uPoJZL0T9olY5n
      required:
        - client_id
        - client_secret
    
    GetTokenResponse:
      type: object
      properties:
        access_token:
          type: string
          example: eyJraWQiOiI4ZjYwYmRiMy1mYTNjLTRjZTAtYWZhOS04ZWY3MjA4ZTE0NzIiLCJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJTaGFib2RpIExBQVMiLCJhdWQiOiJTaGFib2RpIEFFUCIsInN1YiI6IjkzZjJjODc5LWMzZjktNGY5MS05ZDc0LTJjODRjYzgwODFkZCIsInByZWZlcnJlZF91c2VybmFtZSI6IlNOQlAgREVNTyBBUFBMSUNBVElPTiAtIEplZmYiLCJwb3J0Ijo1NTU5LCJpcHY0IjoiMTcyLjU2LjEwNS4yNiIsImRpcmVjdGlvbiI6IkRMIiwidHJhZmZpYyI6IlRDUCIsImRldmVkZ2UiOnsiaWQiOiJ0bW9uLTltSDZoN2tyTzdxSmU3NllZOEJOZ082cGZDNmJ0TEZSIiwic2VjcmV0IjoiM0tBOUJwaUdHSUlVWGhFTSJ9LCJ1ZXMiOlsxXSwic2NvcGUiOiJhcGk6c2V0QlcgYXBpOlBjZkF1dGhvcml6YXRpb25Ob3JtRHJ1aWROQiBhcGk6UGNmQXV0aG9yaXphdGlvbk5vcm1PcGVuNUdTTkIgYXBpOlBjZkF1dGhvcml6YXRpb25EaXNjRHJ1aWROQiBhcGk6UGNmQXV0aG9yaXphdGlvbkRpc2NPcGVuNUdTTkIiLCJpYXQiOjE3MTE2NDYxMzEsImV4cCI6MTcxMTY0OTczMSwianRpIjoiMzllZjMzMjktMzdjNi00Y2M1LTgzMzMtMmFiNTE1YmEyNDBiIn0.lqPmABVWcYp153Q99j1n9TADVGszI9BpFAGyKwqyzpg
        expires_in:
          type: integer
          example: 3600
        scope: 
          type: string
        token_type:
          type: string
          example: Bearer

    SetBandwidth:
      type: object
      properties:
        device:
          $ref: "#/components/schemas/DeviceInfo"
        maxBitRate: 
          $ref: "#/components/schemas/maxBitRate"
        guaranteedBitRate:
          $ref: "#/components/schemas/guaranteedBitRate"
        direction:
          $ref: "#/components/schemas/direction"
        duration:
          $ref: "#/components/schemas/duration"
      required:
        - device

    SetBandwidthResponse:
      type: object
      required:
        - transactionId
        - createdTime
        - expiredTime
      properties:
        transactionId:
          $ref: "#/components/schemas/transactionId"
        remainingTime:     
          $ref: "#/components/schemas/remainingTime"

    GetBandwidthResponse:
      type: object
      properties:
        sessions:
          type: array
          items:
            properties:
              device:
                $ref: "#/components/schemas/DeviceInfo"
              maxBitRate: 
                $ref: "#/components/schemas/maxBitRate"
              guaranteedBitRate:
                $ref: "#/components/schemas/guaranteedBitRate"
              direction:
                $ref: "#/components/schemas/direction"
              remainingTime:     
                $ref: "#/components/schemas/remainingTime"

    SetLatency:
      type: object
      properties:
        device:
          $ref: "#/components/schemas/DeviceInfo"
        latency: 
          $ref: "#/components/schemas/latency"
        duration:
          $ref: "#/components/schemas/duration"
      required:
        - device
        - latency

    SetLatencyResponse:
      type: object
      required:
        - transactionId
        - createdTime
        - expiredTime
      properties:
        transactionId:
          $ref: "#/components/schemas/transactionId"
        remainingTime:     
          $ref: "#/components/schemas/remainingTime"

    GetLatencyResponse:
      type: object
      properties:
        sessions:
          type: array
          items:
            properties:
              device:
                $ref: "#/components/schemas/DeviceInfo"
              latency:
                $ref: "#/components/schemas/latency"
              remainingTime:     
                $ref: "#/components/schemas/remainingTime"

    SetJitter:
      type: object
      properties:
        device:
          $ref: "#/components/schemas/DeviceInfo"
        jitter: 
          $ref: "#/components/schemas/jitter"
        duration:
          $ref: "#/components/schemas/duration"
      required:
        - device
        - jitter

    SetJitterResponse:
      type: object
      required:
        - transactionId
        - createdTime
        - expiredTime
      properties:
        transactionId:
          $ref: "#/components/schemas/transactionId"
        remainingTime:     
          $ref: "#/components/schemas/remainingTime"

    GetJitterResponse:
      type: object
      properties:
        sessions:
          type: array
          items:
            properties:
              device:
                $ref: "#/components/schemas/DeviceInfo"
              jitter:
                $ref: "#/components/schemas/jitter"
              remainingTime:     
                $ref: "#/components/schemas/remainingTime"

    GetLocationResponse:
      type: object
      properties:
        location:
          type: array
          items:
            properties:
              device:
                $ref: "#/components/schemas/DeviceInfo"
              latitude:
                $ref: "#/components/schemas/latitude"
              longitude:
                $ref: "#/components/schemas/longitude"
              altitude:
                $ref: "#/components/schemas/altitude"   


    GetDeviceStatusResponse:
      type: object
      properties:
        deviceStatus:
          type: array
          items:
            properties:
              deviceId:
                description: Device identifier
                type: integer
                example: 4
              connectedNetwork:
                description: 0 indicates no connectivity - non-zero response represens the network identifier of the connected device
                type: integer
                example: 3
              signalStrength:
                description: Scale from 0 to 5. 0 indicates no connectivity while 5 indicates the highest signal strength of the specified device
                type: integer
                example: 4

    GetDeviceUtilzationResponse:
      type: object
      properties:
        deviceUtilization:
          type: array
          items:
            properties:
              deviceId:
                description: Device identifier
                type: integer
                example: 4
              utilization:
                type: integer
                description: Utilization of a device in comparison to its allocated guranteed bit rate. Example - device is configured for 5000 Kbps guarenteed bit rate but is only using 1000 Kbps - this is 20% utilization of allocated bandwidth. Parameter not returned when no active bandwidth session established.
                example: 57

    CreateSubscription:
      type: object
      properties:
        topic:
          $ref: "#/components/schemas/topic"
        minThreshold:
          $ref: "#/components/schemas/minThreshold"
        maxThreshold:
          $ref: "#/components/schemas/maxThreshold"
        filters: 
          $ref: "#/components/schemas/filters"
        notification:
          $ref: "#/components/schemas/notification"
        expireTime:
          $ref: "#/components/schemas/expiredTime"
      required:
        - topic
        - notification

    CreateSubscriptionResponse:
      type: object
      required:
        - transactionId
        - expiredTime
      properties:
        transactionId:
          $ref: "#/components/schemas/transactionId"
        createdTime:
          $ref: "#/components/schemas/createdTime"
        expiredTime:
          $ref: "#/components/schemas/expiredTime"

    CreateCallback:
      type: object
      required:
        - subscriptionId
        - event
        - eventDetails
      properties:
        subscriptionId:
          $ref: "#/components/schemas/subscriptionId"
        event:
          $ref: "#/components/schemas/event"
        eventDetails:
          $ref: "#/components/schemas/eventDetails"

    GetSubscriptionResponse:
      type: array
      items:
        properties:
          subscriptionDetails:
            $ref: "#/components/schemas/SubscriptionDetails"
                
    SubscriptionDetails:
      type: object
      properties:
        subscriptionId:
          $ref: "#/components/schemas/subscriptionId"
        topic:
          $ref: "#/components/schemas/topic"
        minThreshold:
          $ref: "#/components/schemas/minThreshold"
        maxThreshold:
          $ref: "#/components/schemas/minThreshold"
        filters:
          $ref: "#/components/schemas/filters"
        notification:
          $ref: "#/components/schemas/notification"
        createdTime:
          $ref: "#/components/schemas/createdTime"
        expiredTime:
          $ref: "#/components/schemas/expiredTime"

    DeviceInfo:
      description: |
          End-user equipment able to connect to a network. Examples of devices include cameras, AGVs, drones, IoT sensors/actuators, etc.     
      type: object
      properties:
        deviceId:
          type: integer
          example: 3
       # MAC:
       #   type: string
       #   example: 00-B0-D0-63-C2-26
          
    transactionId:
      type: string
      example: 43571235
      
    createdTime:
      type: string
      format: date-time
      example: "2024-03-13T09:12:28Z"
      
    expiredTime:
      type: string
      format: date-time 
      example: "2024-04-13T09:12:28Z"

    remainingTime:
      description: Time remaining before expiry
      type: integer
      example: 60000
      
    maxBitRate:
      description: |
            The MBR value determines the highest bit rate that a device can be served by the access network, ensuring that data transmission does not exceed this specified rate. Unit for MBR is``Kbps``
      type: integer
      example: 4096
      
    guaranteedBitRate:
      description: |
            Guaranteed bit rate (GBR) rovides a specific minimum bit rate that is always reserved by the network for the UE. GBR bearers are typically used for time-critical applications where a guaranteed flow bit rate is essential. Unit for GBR is``Kbps``
      type: integer
      example: 4096
      
    direction:
      type: string
      enum:
        - uplink
        - downlink
        
    duration:
      description: |
            Duration of the bandwidth session in miliseconds. When not specified, default is 1 hour.
      type: integer
      minimum: 1000
      maximum: 86400000
      default: 3600000
      example: 300000

    latency:
      description: |
            Latency in miliseconds.
      type: integer
      minimum: 1
      maximum: 1000
      example: 120
      
    jitter:
      description: |
            Jitter in miliseconds. 
      type: integer
      minimum: 5
      maximum: 100
      example: 40

    latitude:
      description: |
            Latitude of the specified device 
      type: string
      example: "-75.75619047340287"

    longitude:
      description: |
            Longitude of the specified device 
      type: string
      example: "45.3189923087387"
    
    altitude:
      description: |
            Altitude of the specified device in meters
      type: number
      example: 3.56


    topic:
      description: |
            Event type for notification callback (i.e connectivity, deviceUtilization, etc)
      type: string
      enum:
        - connectivity
        - deviceUtilization
      example: "connectivity"

    filters:
      description: | 
            Scope of devices for notification.
              examples:

                * - net2.* indicates all devices in network 2 are in scope
                * - net3.device5 indicates that only device 5 from network 3 is in scope
            Note: No filters indicate all devices from all applications as default notification
      type: array
      items:
        type: string
        example: ["net2.*", "net3.device5","app"]
        anyOf:
          - pattern: '^[^.]+[.][^.]+$'

    notification:
      description: |
            desitnation host and token required for callback
      type: object
      properties: 
        destination:
          type: string
          example: "https://application-server.com"
        token:
          type: string
          example: "---------- token ----------"

    subscriptionId:
      description: The subscription identifier, used for querying or deleting subscriptions"
      type: string
      example: "25487591"

    event:
      description: Event type described in the notification callback
      type: string
      example: "connectivity"
    
    eventDetails:
      description: Details of the event
      type: object
      properties:
        deviceId:
          type: integer
          example: 3
        status:
          type: string
          example: "disconnected"
        timestamp:
          description: Time the event occured
          type: string
          format: date-time
          example: "2024-03-13T09:12:28Z"

    minThreshold: 
      type: integer
      description: Identifies a minimum threhold trigger for event notification. Example - send a notification when network utilization reaches 80%
      example: 30
      default: 25    

    maxThreshold: 
      type: integer
      description: Identifies a maximum threhold trigger for event notification. Example - send a notification when network utilization reaches 80%
      example: 90
      default: 75    

    ErrorInfo:
          type: object
          description: Error information  
          required:
            - status
            - code
            - message
          properties:
            status:
              type: integer
              description: HTTP status code returned along with this error response
            code:
              type: string
              description: Code given to this error
            message:
              type: string
              description: Detailed error description    
        
  responses:
        Generic400:
          description: Invalid argument
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorInfo"
              example:
                status: 400
                code: INVALID_ARGUMENT
                message: "Invalid argument"
        
        Generic401:
          description: Unauthenticated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorInfo"
              example:
                status: 401
                code: UNAUTHENTICATED
                message: "Authorization failed: ..."
        
        Generic403:
          description: Permission denied
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorInfo"
              example:
                status: 403
                code: PERMISSION_DENIED
                message: "Operation not allowed: ..."
        
        Generic404:
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorInfo"
              example:
                status: 404
                code: NOT_FOUND
                message: "The specified resource is not found"
                
        SessionNotFound404:
          description: Session not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorInfo"
              example:
                status: 404
                code: NOT_FOUND
                message: "Session for specified deviceId does not exist"

        SubscriptionNotFound404:
          description: Subscription not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorInfo"
              example:
                status: 404
                code: NOT_FOUND
                message: "Subscription for specified subscriptionId does not exist"
        
        Generic409:
          description: Conflict
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorInfo"
              example:
                status: 409
                code: Conflict
                message: "There is conflict in the request"

        Generic422:
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorInfo"
              example:
                status: 500
                code: INTERNAL
                message: "Unable to process requested operation on specified device"

        Generic500:
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorInfo"
              example:
                status: 500
                code: INTERNAL
                message: "Internal server error"
                
        
        Generic503:
          description: Service unavailable
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorInfo"
              example:
                status: 503
                code: UNAVAILABLE
                message: "Service unavailable"