Skip to main content

An Application Layer Interface for Non-IP device control (NIPC)
draft-brinckman-nipc-01

Document Type Active Internet-Draft (asdf WG)
Authors Bart Brinckman , Rohit Mohan , Braeden Sanford
Last updated 2024-07-03 (Latest revision 2024-04-21)
RFC stream Internet Engineering Task Force (IETF)
Intended RFC status Proposed Standard
Formats
Additional resources Mailing list discussion
Stream WG state Adopted by a WG
Document shepherd (None)
IESG IESG state I-D Exists
Consensus boilerplate Yes
Telechat date (None)
Responsible AD (None)
Send notices to (None)
draft-brinckman-nipc-01
Network Working Group                                       B. Brinckman
Internet-Draft                                                  R. Mohan
Intended status: Standards Track                           Cisco Systems
Expires: 23 October 2024                                      B. Sanford
                                                                 Philips
                                                           21 April 2024

    An Application Layer Interface for Non-IP device control (NIPC)
                        draft-brinckman-nipc-01

Abstract

   This memo specifies RESTful application layer interface for gateways
   providing operations against non-IP devices.  The described interface
   is extensible.  This memo initially describes Bluetooth Low Energy
   and Zigbee as they are the most commonly deployed.

Status of This Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF).  Note that other groups may also distribute
   working documents as Internet-Drafts.  The list of current Internet-
   Drafts is at https://datatracker.ietf.org/drafts/current/.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   This Internet-Draft will expire on 23 October 2024.

Copyright Notice

   Copyright (c) 2024 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents (https://trustee.ietf.org/
   license-info) in effect on the date of publication of this document.
   Please review these documents carefully, as they describe your rights
   and restrictions with respect to this document.  Code Components
   extracted from this document must include Revised BSD License text as
   described in Section 4.e of the Trust Legal Provisions and are
   provided without warranty as described in the Revised BSD License.

Brinckman, et al.        Expires 23 October 2024                [Page 1]
Internet-Draft                    NIPC                        April 2024

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   3
     1.1.  Terminology . . . . . . . . . . . . . . . . . . . . . . .   5
   2.  Non-IP Control Functions  . . . . . . . . . . . . . . . . . .   5
     2.1.  Approach  . . . . . . . . . . . . . . . . . . . . . . . .   6
       2.1.1.  Common base schema  . . . . . . . . . . . . . . . . .   6
       2.1.2.  Protocol extensions . . . . . . . . . . . . . . . . .   7
       2.1.3.  Response  . . . . . . . . . . . . . . . . . . . . . .   8
       2.1.4.  Categories of operations supported  . . . . . . . . .   9
       2.1.5.  Connecting to the Non-IP Control Interface  . . . . .   9
     2.2.  Connectivity  . . . . . . . . . . . . . . . . . . . . . .   9
       2.2.1.  Binding . . . . . . . . . . . . . . . . . . . . . . .   9
       2.2.2.  Binding by id . . . . . . . . . . . . . . . . . . . .  11
       2.2.3.  Connection  . . . . . . . . . . . . . . . . . . . . .  12
       2.2.4.  Connections by id . . . . . . . . . . . . . . . . . .  15
       2.2.5.  Discover services supported by a device . . . . . . .  16
       2.2.6.  Discover services supported by a device by id . . . .  16
     2.3.  Data  . . . . . . . . . . . . . . . . . . . . . . . . . .  17
       2.3.1.  Attribute . . . . . . . . . . . . . . . . . . . . . .  17
       2.3.2.  Subscription  . . . . . . . . . . . . . . . . . . . .  20
       2.3.3.  Subscriptions by id . . . . . . . . . . . . . . . . .  23
       2.3.4.  Subscriptions by topic  . . . . . . . . . . . . . . .  24
       2.3.5.  Broadcast . . . . . . . . . . . . . . . . . . . . . .  24
     2.4.  Registrations . . . . . . . . . . . . . . . . . . . . . .  26
       2.4.1.  Topic registration  . . . . . . . . . . . . . . . . .  26
       2.4.2.  Topic registrations by id . . . . . . . . . . . . . .  28
       2.4.3.  Topic registrations by data app . . . . . . . . . . .  29
       2.4.4.  Topic registrations by topic name . . . . . . . . . .  30
       2.4.5.  File registration . . . . . . . . . . . . . . . . . .  30
       2.4.6.  file registrations by file name . . . . . . . . . . .  32
   3.  NIPC Extensibility  . . . . . . . . . . . . . . . . . . . . .  33
     3.1.  Protocol extensions . . . . . . . . . . . . . . . . . . .  33
     3.2.  Interface extensions  . . . . . . . . . . . . . . . . . .  34
       3.2.1.  Write file  . . . . . . . . . . . . . . . . . . . . .  35
       3.2.2.  Read conditional file . . . . . . . . . . . . . . . .  35
       3.2.3.  Bulk  . . . . . . . . . . . . . . . . . . . . . . . .  35
   4.  Publish/Subscribe Interface . . . . . . . . . . . . . . . . .  36
   5.  Examples  . . . . . . . . . . . . . . . . . . . . . . . . . .  36
     5.1.  BLE Advertisement . . . . . . . . . . . . . . . . . . . .  36
     5.2.  BLE Attribute Read/Write  . . . . . . . . . . . . . . . .  36
     5.3.  Zigbee Attribute Read/Write . . . . . . . . . . . . . . .  37
   6.  Security Considerations . . . . . . . . . . . . . . . . . . .  37
   7.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .  37
   8.  Normative References  . . . . . . . . . . . . . . . . . . . .  37
   Appendix A.  OpenAPI definition . . . . . . . . . . . . . . . . .  38
   Appendix B.  Protobuf definition  . . . . . . . . . . . . . . . . 108
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . . 109

Brinckman, et al.        Expires 23 October 2024                [Page 2]
Internet-Draft                    NIPC                        April 2024

1.  Introduction

   Use cases in building management, healthcare, workplaces,
   manufacturing, logistics and hospitality have introduced low-power
   devices into these environments.  These devices typically do not
   support IP-based interfaces, hence there is a need for gateway
   functions to allow these devices to communicate with the applications
   that manage them.

       +-------------+              +---------+              +--------+
       | Application |<------------>| Gateway |<------------>| Non-IP |
       |    app      |   IP-based   |         |    Non-IP    | Device |
       +-------------+   Operation  +---------+   Operation  +--------+

                    Figure 1: Gateway for non-IP Devices

   In abscence of a standard describing how applications communicate
   with such non-IP devices, vertically integrated infrastructure
   prolifilates and applications have bespoke integrations with that
   infrastructure for every use case.  The Application interfaces are
   non-standard.  This stunts the eco-system growth.  At the same time,
   wireless access points have been deployed nearly everywhere, many of
   which have soft or separate radios that can transmit and receive
   different frame types, such as [BLE53] and [Zigbee22].  To avoid the
   need for parallel infrastructure and bespoke application integration,
   a standardized gateway function is necessary.

   The gateway provides at a minimum the following functions:

   *  authentication and authorization of application clients that will
      access devices

   *  the ability to onboard devices that are intended to be deployed
      within the use case

   *  maintenance of an inventory of onboarded devices that are intended
      to access and be accessed by the deployment and applications.

   *  interfaces that allow for bi-directional communication to non-IP
      devices

   *  one or more channels to process requests, responses, and
      asymmetric communciations with the non-IP radio resources (Access
      Points) in the system.

Brinckman, et al.        Expires 23 October 2024                [Page 3]
Internet-Draft                    NIPC                        April 2024

   Combined with a provisioning interface such as
   [I-D.shahzad-scim-device-model], this specification supports these
   aspects, specifically focusing on providing bi-directional
   communication with non-IP devices.

                               +-----------------------------------+
                               |                                   |
       +-----------+   Request |  +---------+                      |
       | onboarding|------------->|  SCIM   |                      |
       |    app    |<-------------| Server  |                      |
       +-----------+  Ctrl Endpt  +---------+                      |
                               |                                   |
       +-----------+           |  +------------+  +-------+  +--+  |
       |  Control  |>...REST...|.>|            |..|  AP   |..|D |  |
       |     &     |           |  |   Gateway  |  +-------+  +--+  |
       | Telemetry |<...MQTT...|.<|            |                   |
       |    Apps   |           |  +------------+                   |
       +-----------+           |                                   |
                               |       Network Deployment          |
                               +-----------------------------------+

                        Figure 2: Basic Architecture

   Figure 2 shows us the application layer gateway (ALG), an access
   point (AP), and a device (D) in the enterprise environment.  The role
   of the ALG is to provide a application gateway to non-IP devices
   connecting into one or more AP.  Applications implementing this memo
   can leverage RESTful interfaces to communicate with these devices and
   subscribe to streaming data or broadcasts levering MQTT.

   The flow of operations are as follows:

   1.  The operator of the network deployment authorizes application(s)
       to perform operations on the Gateway.  This happens out of band
       and may be accomplished by means of exchanging tokens or public
       keys.  Authorization can be role-based:
       a.  Authorize an onboarding application against a SCIM endpoint
       supported by the gateway.
       b.  Provision and authorize applications that may control
       devices.
       c.  Provision and authorize applications that may receive
       telemetry.

   2.  The authorized application can now provision one or more devices
       on the gateway leveraging SCIM.

   Steps 1 and 2 are not within the scope of this specification, but are
   provided for context.

Brinckman, et al.        Expires 23 October 2024                [Page 4]
Internet-Draft                    NIPC                        April 2024

   1.  The authorized application can perform RESTful calls to the
       gateway in order to establish bi-directional communication to one
       or more devices.  Optionally, set up a publish/subcribe topic to
       receive streaming data from a device (telemetry interface).

   2.  Optionally, an application can receive streaming data on a pub/
       sub topic configured by the control interface (telemetry
       interface).

   Step 3 and 4 are the subject of this memo.

   This specification is organized into three sections:

   *  Basic non-IP control functions described in narrative.

   *  Extensibility of the interfaces.

   *  A specification that can be mapped to a publication/subscribe
      interface, such as MQTT.

   *  Examples of use cases leveraging both BLE and Zigbee-based
      devices.

   *  OpenAPI definitions for the control interface and Protobuf
      definitions for the streaming data interface

1.1.  Terminology

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
   "OPTIONAL" in this document are to be interpreted as described in BCP
   14 [RFC2119] [RFC8174] when, and only when, they appear in all
   capitals, as shown here.

2.  Non-IP Control Functions

   This section will describe a standardized protocol-agnostic interface
   that allows the application to establish bi-directional communication
   with a non-IP device, such as a BLE or Zigbee device.  The interface
   will be supported on a gateway as show in Figure 2.

Brinckman, et al.        Expires 23 October 2024                [Page 5]
Internet-Draft                    NIPC                        April 2024

2.1.  Approach

   In non-IP protocols such as BLE or Zigbee, a number of basic
   operations are defined that are similar across protocols.  Examples
   of this are read and write data.  Devices may choose to implement all
   of the operations or a subset.  For example in BLE a device may
   choose to implement a binding, but could also allow connection
   without a binding.  In this memo we have therefore defined a control
   interface that exposes these basic operations with a communications
   protocol-agnostic schema, with protocol specific extensions to
   transmit and receive attributes that are specific to the
   communications protocol supported by the device.  This enables
   extensions to integrate new non-ip communications protocols, without
   the need to update the base schema.

       ID
        - device/group attributes
           |
           |> BLE
           |     - BLE attributes
           |
           |> Zigbee
                 - Zigbee attributes

                        Figure 3: Extensible Schema

   As shown in Figure 3, the control interface addresses device and
   group objects as IDs, hence the requirement to declare a device to
   the gateway before addressing a NIPC operation to the device.  This
   is done by means of SCIM.  A NIPC operation can either be performed
   against a device-id or a group-id.  The gateway will leverage
   information from the SCIM object to execute a specific NIPC
   operation.  For example, keying material found in the SCIM object may
   be required to connect to a device.  Please refer to
   [I-D.shahzad-scim-device-model] for more information on SCIM device
   objects.

   Apart from enabling bi-directional communication with non-ip devices,
   NIPC also allows an application to register pub/sub topics in order
   to support a programmable data streaming interface.

2.1.1.  Common base schema

   As described, most operations are executed against a device or a
   group.  Control operations refer to either of these as "Object" with
   an ID as an identifier.  The common schema for Object is defined as
   follows:

Brinckman, et al.        Expires 23 October 2024                [Page 6]
Internet-Draft                    NIPC                        April 2024

    +============+=====+======+======================================+
    | Attribute  | Req | Type | Example                              |
    +============+=====+======+======================================+
    | id         | T   | uuid | 12345678-1234-5678-1234-56789abcdef4 |
    +------------+-----+------+--------------------------------------+
    | type       | T   | enum | device                               |
    +------------+-----+------+--------------------------------------+
    | technology | F   | enum | ble                                  |
    +------------+-----+------+--------------------------------------+

                     Table 1: Definition of an Object

   where-

   *  id is the id returned in the response when registering a device
      against a SCIM server.

   *  type is either "group" or "device".

   *  technology is the radio technology extension(s) supported by the
      device, in this memo either "ble" or "zigbee".

2.1.2.  Protocol extensions

   An object can support one or more communications protocols.  These
   attributes must be described in a protocol object, for example a
   "ble" or a "zigbee" object.

   +===========+=====+========+========================================+
   | Attribute | Req | Type   | Example                                |
   +===========+=====+========+========================================+
   | ble       | T   | object | an object with BLE-                    |
   |           |     |        | specific attributes                    |
   +-----------+-----+--------+----------------------------------------+
   | zigbee    | T   | object | an object with Zigbee-                 |
   |           |     |        | specific attributes                    |
   +-----------+-----+--------+----------------------------------------+

                        Table 2: Protocol extensions

   where-

   *  "ble" is an object containing attributes that are specific to the
      BLE protocol.

   *  "zigbee" is an object containing attributes that are specific to
      the Zigbee protocol.

Brinckman, et al.        Expires 23 October 2024                [Page 7]
Internet-Draft                    NIPC                        April 2024

   *  Other protocol extensions can be added

2.1.3.  Response

   As most operations have a common base schema, so do responses.  As
   mandatory, a status is returned, optionally also device id and
   request id.

   Success response:

     +===========+=====+======+======================================+
     | Attribute | Req | Type | Example                              |
     +===========+=====+======+======================================+
     | status    | T   | enum | SUCCESS                              |
     +-----------+-----+------+--------------------------------------+
     | id        | F   | uuid | 12345678-1234-5678-1234-56789abcdef4 |
     +-----------+-----+------+--------------------------------------+
     | requestID | F   | uuid | abcd0987-1234-5678-1234-56789abcdef4 |
     +-----------+-----+------+--------------------------------------+

                         Table 3: Success response

   Failure response:

    +===========+=====+========+======================================+
    | Attribute | Req | Type   | Example                              |
    +===========+=====+========+======================================+
    | status    | T   | enum   | SUCCESS                              |
    +-----------+-----+--------+--------------------------------------+
    | errorCode | T   | int    | 12                                   |
    +-----------+-----+--------+--------------------------------------+
    | reason    | T   | string | "Not Found"                          |
    +-----------+-----+--------+--------------------------------------+
    | requestID | F   | uuid   | abcd0987-1234-5678-1234-56789abcdef4 |
    +-----------+-----+--------+--------------------------------------+

                         Table 4: Failure response

   where-

   *  status is the status of the request, either "SUCCESS" or
      "FAILURE".  In case of failure an error code and reason are added

   *  id is the id the operation was executed against, found in the
      request

   *  requestID is a correlation ID that can be used for end-to-end
      tracing.

Brinckman, et al.        Expires 23 October 2024                [Page 8]
Internet-Draft                    NIPC                        April 2024

   *  errorCode is a numerical value representing the error

   *  reason is a human readable explanation of why the error occurred

2.1.4.  Categories of operations supported

   The common operations are categorized in common categories that
   describe high level sets of functionalities.  Each of the NIPC
   operations belong to a category.  The categories are:

   *  /connectivity: Allows an application to establish connectivity
      with a device (if so required by the technology)

   *  /data: Allows applications to exchange data with a device

   *  /registrations: Allows an application to make registrations in the
      network, for example to register a pub/sub topic

   *  /extensions: This is a category of operations that leverage basic
      connectivity, data or registration operations, but are optimized
      for application usage, allowing applications to perform functions
      with a reduced number of round-trips.  An example of this is the
      the bulk operation, allowing to send multiple operations is one
      operation.  This category also allows for further extensions based
      on the basic operations.

2.1.5.  Connecting to the Non-IP Control Interface

   NIPC makes use of RESTful HTTP[RFC9114].  The connection endpoint is
   provided out of band, most likely through the SCIM devices model
   extension, in which an authorized application can be registered for a
   SCIM object.  Similarly authentication of the interface can be
   specified using that SCIM interface.  It may be based on a device
   certificate or an authorization token.

2.2.  Connectivity

   /connectivity

   Connectivity elements are elements that allow operations that
   establish or tear down associations & connectivity with devices.
   They also allow discovery of services that can be accessed during the
   connection.

2.2.1.  Binding

   /connectivity/binding

Brinckman, et al.        Expires 23 October 2024                [Page 9]
Internet-Draft                    NIPC                        April 2024

   The binding element allows an application to request a binding or
   association to a device.

   Operations:

   *  Create binding: POST

   *  Return active bindings: GET

   *  Delete binding: DELETE

2.2.1.1.  Create a Binding

   Method: POST /connectivity/binding

   Description: Creates a binding with a device

   Parameters: None

   Request Body: an Object as defined in Table 1

   Response: See Table 3 for success, and Table 4 for failed responses.

2.2.1.2.  Return active bindings

   Method: GET /connectivity/binding

   Description: Returns one or more bindings, based on ids provided in
   parameters (none = return all)

   Parameters: One of following options: - None: return all bindings
   this application made - single id: return binding for this id - comma
   separated ids: return bindings for multiple ids

   Response: An Array of bindings with contents as shown in Table 5
   below or Table 4 for failed responses.

    +===========+=====+=======+======================================+
    | Attribute | Req | Type  | Example                              |
    +===========+=====+=======+======================================+
    | status    | T   | enum  | SUCCESS                              |
    +-----------+-----+-------+--------------------------------------+
    | requestID | F   | uuid  | abcd0987-1234-5678-1234-56789abcdef4 |
    +-----------+-----+-------+--------------------------------------+
    | bindings  | T   | array | Array of BLE or Zigbee ids           |
    +-----------+-----+-------+--------------------------------------+

                        Table 5: Binding response

Brinckman, et al.        Expires 23 October 2024               [Page 10]
Internet-Draft                    NIPC                        April 2024

2.2.1.3.  Delete a binding

   Method: DELETE /connectivity/binding

   Description: Delete one or more bindings, based on ids provided in
   parameters

   Parameters: One of following options: - None: delete all bindings
   this application made - single id: delete binding for this id - comma
   separated ids: delete bindings for multiple ids

   Response: See Table 3 for success, and Table 4 for failed responses.

2.2.2.  Binding by id

   /connectivity/binding//id/{id}

   The binding by id element allows an application to request a binding
   or association to a device by id, which provides a simpler interface
   than standard binding element, but pertains to a single device only.

   Operations:

   *  Create binding by id: POST

   *  Return active binding by id: GET

   *  Delete binding by id: DELETE

2.2.2.1.  Create a Binding by id

   Method: POST /connectivity/binding/id/{id}

   Description: Creates a binding by id

   Parameters: id

   Response: See Table 3 for success, and Table 4 for failed responses.

2.2.2.2.  Return active binding by id

   Method: GET /connectivity/binding//id/{id}

   Description: Returns a binding by id Parameters: id

   Response: See Table 3 for success, and Table 4 for failed responses.

Brinckman, et al.        Expires 23 October 2024               [Page 11]
Internet-Draft                    NIPC                        April 2024

2.2.2.3.  Delete binding by id

   Method: DELETE /connectivity/binding/id/{id}

   Description: Delete a binding by id

   Parameters: id

   Response: See Table 3 for success, and Table 4 for failed responses.

2.2.3.  Connection

   /connectivity/connection

   The connection element allows an application to request to connect to
   a device.

   Operations:

   *  Connect to a device: POST

   *  Return active connections: GET

   *  Disconnect a device: DELETE

2.2.3.1.  Connect to a device

   Method: POST /connectivity/connection

   Description: Connect to a device

   Parameters: None

   Request Body: - an Object, as defined in Table 1 - optionally a set
   of services to be discovered.  These are supplied in protocol-
   specific extensions, as defined in Table 2.  In the case of BLE,
   service discovery is performed when connecting to a device.
   Optionally, service discovery may be limited to services defined in
   the "ble" protocol extension.  The services to be discovered can be
   added in an array, as well as optional caching parameters.  Please
   see table below Table 6 for a definition of the content of the BLE
   protocol extension for limited service discovery

Brinckman, et al.        Expires 23 October 2024               [Page 12]
Internet-Draft                    NIPC                        April 2024

         +================+=====+=========+=====================+
         | Attribute      | Req | Type    | Example             |
         +================+=====+=========+=====================+
         | services       | T   | array   | Array of serviceIDs |
         |                |     |         | to be discovered    |
         +----------------+-----+---------+---------------------+
         | cached         | F   | boolean | no                  |
         +----------------+-----+---------+---------------------+
         | cacheIdlePurge | F   | int     | 3600                |
         +----------------+-----+---------+---------------------+
         | autoUpdate     | F   | boolean | yes                 |
         +----------------+-----+---------+---------------------+

                        Table 6: Service Discovery

   where-

   *  "services" is an array of services defined by their serviceIDs.

   *  "cached" refers to whether the services need to be cached for
      subsequent connects, in order not to perform service discovery on
      each request.

   *  "cacheIdlepurge" defines how long the cache should be maintained
      before purging

   *  some devices support notifications on changes in services,
      "autoUpdate" allows the network to update services based on
      notification (on by default)

   Response: Success responses include standard success response
   attributes as defined in Table 3 and also include cwan array of
   supported services.  This array of supported services in turn
   contains an array of charateristics, which in turn contains an array
   of descriptors, as shown Figure 4.  For a description of the
   attributes found in this array, please refer to Table 7 below.
   Please refer to Table 4 for failed responses.

       services
        - serviceID
           |
           |> characteristics
               - charactericID
               - flags
                  |
                  |> Descriptors
                      - descriptorID

Brinckman, et al.        Expires 23 October 2024               [Page 13]
Internet-Draft                    NIPC                        April 2024

                             Figure 4: Services

   Attributes in the array of services:

   +==================+===+====+======================================+
   | Attribute        |Req|Type| Example                              |
   +==================+===+====+======================================+
   | serviceID        |F  |uuid| abcd0987-1234-5678-1234-56789abcdef4 |
   +------------------+---+----+--------------------------------------+
   | characteristicID |F  |uuid| abcd0987-1234-5678-1234-56789abcdef4 |
   +------------------+---+----+--------------------------------------+
   | flags            |F  |enum| write                                |
   +------------------+---+----+--------------------------------------+
   | descriptorID     |F  |uuid| abcd0987-1234-5678-1234-56789abcdef4 |
   +------------------+---+----+--------------------------------------+

              Table 7: Service Discovery Response Attributes

2.2.3.2.  Return active connections

   Method: GET /connectivity/connection

   Description: Returns one or more active connections, based on ids
   provided in parameters (none = return all).

   Parameters: One of following options: - None: return all active
   connections for this application - single id: return connection
   status for this id - comma separated ids: return connection status
   for multiple ids

   Response: An Array of connections with attributes as defined in
   Table 8 or in case of a failed response, the attributes in Table 4.

   +=============+=====+=======+======================================+
   | Attribute   | Req | Type  | Example                              |
   +=============+=====+=======+======================================+
   | status      | T   | enum  | SUCCESS                              |
   +-------------+-----+-------+--------------------------------------+
   | requestID   | F   | uuid  | abcd0987-1234-5678-1234-56789abcdef4 |
   +-------------+-----+-------+--------------------------------------+
   | connections | T   | array | Array of connections                 |
   +-------------+-----+-------+--------------------------------------+

                       Table 8: Connection response

Brinckman, et al.        Expires 23 October 2024               [Page 14]
Internet-Draft                    NIPC                        April 2024

2.2.3.3.  Disconnect a device

   Method: DELETE /connectivity/connection

   Description: Disconnect one or more devices, based on ids provided in
   parameters

   Parameters: One of following options: - None: Disconnect all devices
   for connections this application made - single id: disconnect device
   with id - comma separated ids: disconnect multiple devices with ids

   Response: See Table 3 for success, and Table 4 for failed responses.

2.2.4.  Connections by id

   /connectivity/connection/id/{id}

   The connection by id element allows an application to request a
   connection to a device by id, which provides a simpler interface than
   standard connection element, but pertains to a single device only.

   Operations:

   *  Connect device by id: POST

   *  Return connection state by id: GET

   *  Disconnect device by id: DELETE

2.2.4.1.  Connect device by id

   Method: POST /connectivity/connection/id/{id}

   Description: Creates a connection by id

   Parameters: id

   Response: See Table 3 for success, and Table 4 for failed responses.

2.2.4.2.  Return connection state by id

   Method: GET /connectivity/connection/id/{id}

   Description: Returns connection state by id Parameters: id

   Response: See Table 3 for success, and Table 4 for failed responses.

Brinckman, et al.        Expires 23 October 2024               [Page 15]
Internet-Draft                    NIPC                        April 2024

2.2.4.3.  Delete connection by id

   Method: DELETE /connectivity/connection/id/{id}

   Description: Delete a binding by id

   Parameters: id

   Response: See Table 3 for success, and Table 4 for failed responses.

2.2.5.  Discover services supported by a device

   /connectivity/services

   The services element allows an application to request a service
   discovery for a device, possibly to update a cache

   Operations:

   *  Discover services: GET

2.2.5.1.  Discover services supported by a device

   Method: GET /connectivity/service

   Description: Discover services supported by a device, this updates
   cache in case services caching is enabled for a connection.

   Parameters: an Object as defined in Table 1 and optionally a set of
   services to be discovered in case not all services should be
   discovered.  These services need to be provided in protocol-specific
   extensions as defined in Table 2.  The services to be discovered can
   be added in this extension in an array, as well as optional caching
   parameters, as described in Table 6.

   Response: A successful response will contain success attributes from
   Table 3 with an array of supported services characteristics and
   descriptors, as shown in Figure 4, with attributes defined in
   Table 7.  Failure Response is the standard response as defined in
   Table 4

2.2.6.  Discover services supported by a device by id

   /connectivity/services/id/{id}

   The services element allows an application to request a service
   discovery for a device by id, possibly to update a cache

Brinckman, et al.        Expires 23 October 2024               [Page 16]
Internet-Draft                    NIPC                        April 2024

   Operations:

   *  Discover services by id: GET

2.2.6.1.  Discover services supported by a device by id

   Method: GET /connectivity/service/id/{id}

   Description: Discover services supported by a device, this updates
   cache in case services caching is enabled for a connection.  This
   method does not support partial service discovery, all services are
   discovered.

   Parameters: an Object id

   Response: A successful response will contain success attributes from
   Table 3 with an array of supported services, characteristics and
   descriptors, as shown in Figure 4, with attributes defined in
   Table 7.  Failure Response is the standard response as defined in
   Table 4.

2.3.  Data

   /data

   Data elements are elements that allow operations to exchange data
   with a device.  This could be reading or writing attributes or
   enabling streaming data.

2.3.1.  Attribute

   /data/attribute

   The attribute element allows an application get an attribute value,
   write, update or delete a value.

   Operations:

   *  Write value: POST

   *  Update value: PUT

   *  Read value: GET

   *  Delete value: DELETE

Brinckman, et al.        Expires 23 October 2024               [Page 17]
Internet-Draft                    NIPC                        April 2024

2.3.1.1.  Writing a value

   Method: POST /data/attribute

   Description: Writes a value to an attribute

   Parameters: None

   Request Body: an Object as defined in Table 1, a value to be written,
   as defined in Table 9 below and an attribute definition in a protocol
   extension from Table 2.  The protocol extension for BLE is defined in
   Table 10 below.  The protocol extension for Zigbee is defined in
   Table 11 below.

               +================+=====+=========+=========+
               | Attribute      | Req | Type    | Example |
               +================+=====+=========+=========+
               | value          | T   | array   | 100     |
               +----------------+-----+---------+---------+
               | forcedResponse | F   | boolean | no      |
               +----------------+-----+---------+---------+

                              Table 9: Value

   where-

   *  value is the value to be written

   *  forcedresponse requests a specific response behavior of the device

   Contents of the BLE protocol extension defining an attribute:

    +================+===+=======+====================================+
    |Attribute       |Req|Type   |Example                             |
    +================+===+=======+====================================+
    |serviceID       |T  |uuid   |abcd0987-1234-5678-1234-56789abcdef4|
    +----------------+---+-------+------------------------------------+
    |characteristicID|T  |uuid   |abcd0987-1234-5678-1234-56789abcdef4|
    +----------------+---+-------+------------------------------------+
    |long            |F  |boolean|no                                  |
    +----------------+---+-------+------------------------------------+

                          Table 10: BLE Attribute

   where-

   *  serviceID defines the Service

Brinckman, et al.        Expires 23 October 2024               [Page 18]
Internet-Draft                    NIPC                        April 2024

   *  characteristic ID defines the service characteristic

   *  long is an optional attribute that allows to force a write type

   Contents of the Zigbee protocol extension defining an attribute:

                     +==+=============+===+=====+====+
                     |  | endpointID  | T | int | 16 |
                     +==+=============+===+=====+====+
                     |  | clusterID   | T | int | 6  |
                     +--+-------------+---+-----+----+
                     |  | attributeID | T | int | 12 |
                     +--+-------------+---+-----+----+
                     |  | type        | T | int | 1  |
                     +--+-------------+---+-----+----+

                         Table 11: Zigbee Attribute

   where-

   *  endpointID defines the Zigbee endpoint that contains a cluster of
      attributes

   *  clusterID defines the Zigbee cluster that contains the attribute

   *  attributeID defines the Zigbee attribute

   *  type defines the Zigbee attribute type

   Response: A successful response will contain success attributes from
   Table 3 with optionally the value written as shown in Table 9.
   Failure Response is the standard response as defined in Table 4

2.3.1.2.  Updating a value

   Method: PUT /data/attribute

   Description: Updates a value to an attribute

   Parameters: None

   Request Body: an Object as defined in Table 1, a value to be written,
   as defined in Table 9 and an attribute definition in a protocol
   extension from Table 2.  The protocol extension for BLE is defined in
   Table 10.  The protocol extension for Zigbee is defined in Table 11.

Brinckman, et al.        Expires 23 October 2024               [Page 19]
Internet-Draft                    NIPC                        April 2024

   Response: A successful response will contain success attributes from
   Table 3 with optionally the value written as shown in Table 9.
   Failure Response is the standard response as defined in Table 4

2.3.1.3.  Read an attribute

   Method: GET /data/attribute

   Description: Reads an attribute from a device

   Parameters: an Object as defined in Table 1 and an attribute
   definition in a protocol extension from Table 2.  The protocol
   extension for BLE is defined in Table 10.  The protocol extension for
   Zigbee is defined in Table 11.

   Response: A successful response will contain success attributes from
   Table 3 with the value read as shown in Table 9.  Failure Response is
   the standard response as defined in Table 4

2.3.1.4.  clear the value from an attribute

   Method: DELETE /data/attribute

   Description: Clear the value from an attribute of a device

   Parameters: an Object as defined in Table 1 and an attribute
   definition in a protocol extension from Table 2.  The protocol
   extension for BLE is defined in Table 10.  The protocol extension for
   Zigbee is defined in Table 11.

   Response: A successful response will contain success attributes from
   Table 3 with the optionally the value as null as shown in Table 9.
   Failure Response is the standard response as defined in Table 4

2.3.2.  Subscription

   /data/subscription

   The subscription element allows an application to ask a device to
   start streaming data attached to a certain attribute.

   Operations:

   *  Start a subscription data stream: POST

   *  Update a subscription data stream value: PUT

   *  Get status of a subscription data stream: GET

Brinckman, et al.        Expires 23 October 2024               [Page 20]
Internet-Draft                    NIPC                        April 2024

   *  Stop a subscription data stream: DELETE

2.3.2.1.  Starting a subscription data stream

   Method: POST /data/subscription

   Description: Start a subcription data stream pertaining to a specific
   attribute

   Parameters: None

   Request Body: an Object as defined in Table 1 and an attribute
   definition in a protocol extension from Table 2.  The protocol
   extension for BLE is defined in Table 10.  The protocol extension for
   Zigbee is defined in Table 11.  Optionally a pub/sub topic can be
   included in the request as defined in Table 12 below.  Including a
   topic allows the app to skip the topic registration process.

   Topic attributes:

       +============+=====+=========+=============================+
       | Attribute  | Req | Type    | Example                     |
       +============+=====+=========+=============================+
       | topic      | F   | string  | "enterprise/hospital/pulse" |
       +------------+-----+---------+-----------------------------+
       | dataFormat | F   | enum    | "default"                   |
       +------------+-----+---------+-----------------------------+
       | replay     | F   | boolean | no                          |
       +------------+-----+---------+-----------------------------+
       | forced_ack | F   | boolean | no                          |
       +------------+-----+---------+-----------------------------+

                             Table 12: Topic

   where-

   *  topic is the pub/sub topic the subscription can be consumed on

   *  dataFormat is the data format in which the pub/sub topic is
      delivered

   *  replay is a boolean which defines whether data should be replayed
      in case of application disconnection

   *  forced ack ignores the attribute definition and forces packet ack
      behavior to the device

   Response: See Table 3 for success, and Table 4 for failed responses.

Brinckman, et al.        Expires 23 October 2024               [Page 21]
Internet-Draft                    NIPC                        April 2024

2.3.2.2.  Updating a subscription data stream

   Method: PUT /data/subscription

   Description: Update parameters of a subscription data stream
   pertaining to a specific attribute

   Parameters: None

   Request Body: an Object as defined in Table 1 and an attribute
   definition in a protocol extension from Table 2.  The protocol
   extension for BLE is defined in Table 10.  The protocol extension for
   Zigbee is defined in Table 11.  Optionally a pub/sub topic can be
   included in the request as defined in Table 12.

   Response: See Table 3 for success, and Table 4 for failed responses.

2.3.2.3.  Get status of a subscription data stream

   Method: GET /data/subscription

   Description: Gets the status of a subscription data stream, success
   if active, failure if not active

   Parameters: an Object as defined in Table 1 and an attribute
   definition in a protocol extension from Table 2.  The protocol
   extension for BLE is defined in Table 10.  The protocol extension for
   Zigbee is defined in Table 11.  Optionally a pub/sub topic can be
   included in the request as defined in Table 12.

   Response: See Table 3 for success, and Table 4 for failed responses.

2.3.2.4.  stop a subscription data stream

   Method: DELETE /data/subscription

   Description: stops a subscription data stream

   Parameters: an Object as defined in Table 1 and an attribute
   definition in a protocol extension from Table 2.  The protocol
   extension for BLE is defined in Table 10.  The protocol extension for
   Zigbee is defined in Table 11.  Optionally a pub/sub topic can be
   included in the request as defined in Table 12.

   Response: See Table 3 for success, and Table 4 for failed responses.

Brinckman, et al.        Expires 23 October 2024               [Page 22]
Internet-Draft                    NIPC                        April 2024

2.3.3.  Subscriptions by id

   /data/subscription/id/{id}

   The subscription by id element allows an application to operate on
   all subscriptions of a specific id.

   Operations:

   *  Return active subscriptions by id: GET

   *  Terminate all subscriptions of an id: DELETE

2.3.3.1.  Return active subscriptions by id

   Method: GET /data/subscription/id/{id}

   Description: Returns connection state by id

   Parameters: id

   Response: Success response as defines in Table 3 and an object called
   "subscriptions" which contains an Array of active subscriptions.
   Each of these include an object as defined in Table 1 and a
   subscription attribute definition in a protocolextension from
   Table 2.  The protocol extension for BLE is defined in Table 10.  The
   protocol extension for Zigbee is defined in Table 11.  Failure
   Response is the standard response as defined in Table 4

2.3.3.2.  Stop active subscriptions by id

   Method: DELETE /data/subscription/id/{id}

   Description: Delete active subscriptions for an id

   Parameters: id

   Response: Success response as defines in Table 3 and an object called
   "subscriptions" which contains an Array of active subscriptions.
   Each of these include an object as defined in Table 1 and a
   subscription attribute definition in a protocolextension from
   Table 2.  The protocol extension for BLE is defined in Table 10.  The
   protocol extension for Zigbee is defined in Table 11.  Failure
   Response is the standard response as defined in Table 4

Brinckman, et al.        Expires 23 October 2024               [Page 23]
Internet-Draft                    NIPC                        April 2024

2.3.4.  Subscriptions by topic

   /data/subscription/topic/{topic}

   The subscription by topic element allows an application to operate on
   all subscriptions of a specific topic.

   Operations: - Return active subscriptions by topic: GET - Terminate
   all subscriptions active on a topic: DELETE

2.3.4.1.  Return active subscriptions by topic

   Method: GET /data/subscription/topic/{topic}

   Description: Returns connection state by topic

   Parameters: topic

   Response: Success response as defines in Table 3 and an object called
   "subscriptions" which contains an Array of active subscriptions.
   Each of these include an object as defined in Table 1 and a
   subscription attribute definition in a protocolextension from
   Table 2.  The protocol extension for BLE is defined in Table 10.  The
   protocol extension for Zigbee is defined in Table 11.  Failure
   Response is the standard response as defined in Table 4

2.3.4.2.  Stop active subscriptions by topic

   Method: DELETE /data/subscription/topic/{topic}

   Description: Delete all active subscriptions for a topic

   Parameters: topic

   Response: Success response as defines in Table 3 and an object called
   "subscriptions" which contains an Array of active subscriptions.
   Each of these include an object as defined in Table 1 and a
   subscription attribute definition in a protocolextension from
   Table 2.  The protocol extension for BLE is defined in Table 10.  The
   protocol extension for Zigbee is defined in Table 11.  Failure
   Response is the standard response as defined in Table 4

2.3.5.  Broadcast

   /data/broadcast

Brinckman, et al.        Expires 23 October 2024               [Page 24]
Internet-Draft                    NIPC                        April 2024

   The broadcast element allows an application to broadcast a message to
   a specific device.  Note that broadcasts can be heard by other
   devices on the same L2 network.

   Operations:

   *  Broadcast message: POST

2.3.5.1.  Broadcasting a message

   Method: POST /data/broadcast

   Description: Broadcasts a message to a device

   Parameters: None

   Request Body: an Object as defined in Table 1 along with broadcast
   parameters, defined below in Table 13.  Defining broadcast attributes
   is mandatory and is done by adding an array of broadcast attributes
   in a protocol extension from Table 2.  The protocol extension for BLE
   broadcasts is defined in Table 14 below.

   Broadcast parameters:

               +===================+=====+======+=========+
               | Attribute         | Req | Type | Example |
               +===================+=====+======+=========+
               | cycle             | T   | enum | single  |
               +-------------------+-----+------+---------+
               | broadcastTime     | F   | int  | 30      |
               +-------------------+-----+------+---------+
               | broadcastInterval | F   | int  | 5       |
               +-------------------+-----+------+---------+

                      Table 13: Broadcast parameters

   where-

   *  cycle determines the repetitiveness of the broadcast, and is
      either single or repeat

   *  broadcastTime is the maximum time in seconds the broadcast should
      run

   *  broadcastInterval is the time between broadcasts in seconds

   Protocol-specific extensions are supplied to identify the attributes
   to be broadcasted.

Brinckman, et al.        Expires 23 October 2024               [Page 25]
Internet-Draft                    NIPC                        April 2024

                   +===========+=====+======+=========+
                   | Attribute | Req | Type | Example |
                   +===========+=====+======+=========+
                   | adType    | T   | byte | ff      |
                   +-----------+-----+------+---------+
                   | adData    | T   | byte | 4c00    |
                   +-----------+-----+------+---------+

                    Table 14: BLE Broadcast Attribute

   where-

   *  adType is the BLE advertisement attribute type

   *  adData is the BLE advertisement attribute data

   Response: See Table 3 for success, and Table 4 for failed responses.

2.4.  Registrations

   /registation

   Registration elements are elements that do not directly execute
   operations on devices but register attributes on the gateway that
   support operations, such attributes are topics for data streaming and
   files to write files.

2.4.1.  Topic registration

   /registration/topic

   The topic registration element allows an application to register a
   pub/ sub topic for the data interface.  By activating a subscription
   on one or more device(s), the application can then publish streaming
   data to that topic.

   Operations:

   *  Register a topic: POST

   *  Update a topic: PUT

   *  Get configuration of one or more topics: GET

   *  Delete a topic: DELETE

Brinckman, et al.        Expires 23 October 2024               [Page 26]
Internet-Draft                    NIPC                        April 2024

2.4.1.1.  Registering a topic

   Method: POST /registration/topic

   Description: Register a pub/sub topic

   Parameters: None

   Request Body: A topic, including data apps that can subscribe to the
   topic as defined in Table 12 and protocol-specific extensions as per
   Table 2 that describe the attributes that will be reported on the
   topic.  In the case of BLE, these are either BLE subscription
   attributes as in Table 10, device connection status, or Broadcast
   (advertisement) data as in Table 14.  For Zigbee, these are Zigbee
   attributes as described in Table 11.

   Response: See Table 3 with a topic name as in Table 15 below for
   success, and Table 4 for failed responses.

   Topic name that was registered:

        +===========+=====+========+=============================+
        | Attribute | Req | Type   | Example                     |
        +===========+=====+========+=============================+
        | topic     | T   | string | "enterprise/hospital/pulse" |
        +-----------+-----+--------+-----------------------------+

                           Table 15: Topic Name

2.4.1.2.  Updating a topic

   Method: PUT /registration/topic

   Description: Update a pub/sub topic

   Parameters: None

   Request Body: A topic, including data apps that can subscribe to the
   topic as defined in Table 12 and protocol-specific extensions as per
   Table 2 that describe the attributes that will be reported on the
   topic.  In the case of BLE, these are either BLE subscription
   attributes as in Table 10, device connection status, or Broadcast
   (advertisement) data as in Table 14.  For Zigbee, these are Zigbee
   attributes as described in Table 11.

   Response: See Table 3 with a topic name as in Table 15 below for
   success, and Table 4 for failed responses.

Brinckman, et al.        Expires 23 October 2024               [Page 27]
Internet-Draft                    NIPC                        April 2024

2.4.1.3.  Get configuration of one or more topics

   Method: GET /registration/topic

   Description: Gets the configuration of one or more topics

   Parameters: A topic name.  Multiple topics can be added by comma-
   separated attributes.

   Response: A success response as in Table 3 with a "topics" object
   containing an array of returned topics names with attribute defined
   in Table 15.  For failed responses see Table 4.

2.4.1.4.  Delete one or more topics

   Method: DELETE /registration/topic

   Description: Delete one or more topics

   Parameters: A topic name.  Multiple topics can be added by comma-
   separated attributes.

   Response: A success response as in Table 3 with a "topics" object
   containing an array of returned topics names with attribute defined
   in Table 15.  For failed responses see Table 4.

2.4.2.  Topic registrations by id

   /registration/topic/id/{id}

   The topic registration by id element allows an application to get or
   delete topic registrations for a specific id.

   Operations:

   *  Return active topics by id: GET

   *  Delete all topics for an id: DELETE

2.4.2.1.  Return active topics by id

   Method: GET /registration/topic/id/{id}

   Description: Returns active topics by id

   Parameters: id

Brinckman, et al.        Expires 23 October 2024               [Page 28]
Internet-Draft                    NIPC                        April 2024

   Response: A success response as in Table 3 with a "topics" object
   containing an array of returned topics names with attribute defined
   in Table 15.  For failed responses see Table 4.

2.4.2.2.  Delete active topics by id

   Method: DELETE /registration/topic/id/{id}

   Description: Deletes active topics by id, will delete all topics that
   are associated with a specific object id.

   Parameters: id

   Response: A success response as in Table 3 with a "topics" object
   containing an array of returned topics names with attribute defined
   in Table 15.  For failed responses see Table 4.

2.4.3.  Topic registrations by data app

   /registration/topic/data-app/{data-app}

   The topic registration by data-app element allows an application to
   get or delete topic registrations for which a specific data-
   application is registered.

   Operations:

   *  Return active topics by data-app: GET

   *  Delete all topics for an data-app: DELETE

2.4.3.1.  Return active topics by data-app

   Method: GET /registration/topic/data-app/{data-app}

   Description: Returns active topics by data-app

   Parameters: data-app

   Response: A success response as in Table 3 with a "topics" object
   containing an array of returned topics names with attribute defined
   in Table 15.  For failed responses see Table 4.

2.4.3.2.  Delete active topics by data-app

   Method: DELETE /registration/topic/data-app/{data-app}

Brinckman, et al.        Expires 23 October 2024               [Page 29]
Internet-Draft                    NIPC                        April 2024

   Description: Deletes active topics by data-app, will delete all
   topics the specified data app is registered for.

   Parameters: data-app

   Response: A success response as in Table 3 with a "topics" object
   containing an array of returned topics names with attribute defined
   in Table 15.  For failed responses see Table 4.

2.4.4.  Topic registrations by topic name

   /registration/topic/{topic}

   The topic registration by topic element allows an application to get
   or delete a topic registration by topic name.

   Operations:

   *  Return active topics by topic name: GET

   *  Delete all topics for a topic name: DELETE

2.4.4.1.  Return active topics by topic name

   Method: GET /registration/topic/{topic}

   Description: Returns active topics by topic name

   Parameters: topic

   Response: A success response as in Table 3 with a topic name as
   defined in Table 15.  For failed responses see Table 4.

2.4.4.2.  Delete active topics by topic name

   Method: DELETE /registration/topic/{topic}

   Description: Deletes active topics by topic name

   Parameters: topic

   Response: A success response as in Table 3 with a topic name as
   defined in Table 15.  For failed responses see Table 4.

2.4.5.  File registration

   /registration/file

Brinckman, et al.        Expires 23 October 2024               [Page 30]
Internet-Draft                    NIPC                        April 2024

   The file registration element allows an application to register a
   file. a file can be used in operations to devices (such as an
   attribute)

   Operations:

   *  Register a file: POST

   *  Update a file: PUT

   *  Check if a file exists: GET

   *  Delete a file: DELETE

2.4.5.1.  Registering a file

   Method: POST /registration/file

   Description: Register a file

   Parameters: None

   Request Body: a file or URL point to a file, as described in Table 16
   below.

   File definition:

     +===========+=====+========+===================================+
     | Attribute | Req | Type   | Example                           |
     +===========+=====+========+===================================+
     | filename  | T   | string | "firmware.dat"                    |
     +-----------+-----+--------+-----------------------------------+
     | file      | F   | binary | file                              |
     +-----------+-----+--------+-----------------------------------+
     | bindings  | F   | string | "https://domain.com/firmware.dat" |
     +-----------+-----+--------+-----------------------------------+

                              Table 16: File

   Response: See Table 3 for success, and Table 4 for failed responses.

2.4.5.2.  Updating a file

   Method: PUT /registration/file

   Description: Update a file

   Parameters: None

Brinckman, et al.        Expires 23 October 2024               [Page 31]
Internet-Draft                    NIPC                        April 2024

   Request Body: a file or URL point to a file, as described in Table 16
   below.

   Response: See Table 3 for success, and Table 4 for failed responses.

2.4.5.3.  check presence of a registered file

   Method: GET /registration/file

   Description: Check the presence of a specific file or get all files
   if no file name os present in parameters

   Parameters: filename

   Response: Success as in Table 3 including a "filesnames" object with
   an array of file names as shown in Table 17 or a Failure Response as
   described in Table 4.

   A filenames object with an Array of file names:

               +===========+=====+========+================+
               | Attribute | Req | Type   | Example        |
               +===========+=====+========+================+
               | filename  | T   | string | "firmware.dat" |
               +-----------+-----+--------+----------------+

                            Table 17: File name

2.4.5.4.  delete a registered file

   Method: DELETE /registration/file

   Description: Delete a registered file

   Parameters: filename

   Response: See Table 3 for success, and Table 4 for failed responses.

2.4.6.  file registrations by file name

   /registration/file/{filename}

   The file registration by file name element allows an application to
   get or delete file registrations by file name.

   Operations:

   *  Return file registrations by file name: GET

Brinckman, et al.        Expires 23 October 2024               [Page 32]
Internet-Draft                    NIPC                        April 2024

   *  Delete file registrations by file name: DELETE

2.4.6.1.  Return file registrations by file name

   Method: GET /registration/file/{filename}

   Description: Checks the presence of a file and returns its name

   Parameters: filename

   Response: Success as in Table 3 including a file name as shown in
   Table 17 or a Failure Response as described in Table 4.

2.4.6.2.  Delete file registrations by file name

   Method: DELETE /registration/file/{filename}

   Description: Delete file registrations by file name

   Parameters: filename

   Response: See Table 3 for success, and Table 4 for failed responses.

3.  NIPC Extensibility

   NIPC is extensible in two ways:

   *  Protocol extensions: Protocol extensions can extend NIPC with
      support for new non-IP protocols

   *  interface extensions: Interface extensions allow extensions that
      leverage compound statements of basic elements to simplify common
      operations for applications.

3.1.  Protocol extensions

   As described in Figure 3 the NIPC interface supports protocol
   specific extensions that allow bi-directional communication of
   attributes that are specific to the protocol supported by the device.
   This allows for extensions to the schema to integrate new non-ip
   communications protocols, without the need to update the base schema.

Brinckman, et al.        Expires 23 October 2024               [Page 33]
Internet-Draft                    NIPC                        April 2024

       ID
        - device/group attributes
           |
           |> BLE
           |     - BLE attributes
           |
           |> Zigbee
           |     - Zigbee attributes
           |
           |> Protocol extension
           |     - Protocol extension attributes

                         Figure 5: Extended Schema

   As shown in Figure 5, a protocol extension can be added by adding a
   new technology specific extension to the schema.

   This is performed by adding the new protocol to the technology enum
   in the base objext definition Table 1

   Furthermore, the protocol objects need to be extended with the new
   protocol as well.  Protocol objects will be extended as follows:

        +=============+=====+========+===========================+
        | Attribute   | Req | Type   | Example                   |
        +=============+=====+========+===========================+
        | ble         | T   | object | an object with BLE-       |
        |             |     |        | specific attributes       |
        +-------------+-----+--------+---------------------------+
        | zigbee      | T   | object | an object with Zigbee-    |
        |             |     |        | specific attributes       |
        +-------------+-----+--------+---------------------------+
        | newProtocol | T   | object | an object with            |
        |             |     |        | newProtocol-specific attr |
        +-------------+-----+--------+---------------------------+

                   Table 18: Adding Protocol extensions

   In the new protocol object, protocol specific attributes can be
   added.

3.2.  Interface extensions

   /extensions

   The interface extension elements are freely extendible interfaces.
   These elements leverage the basic NIPC defined elements and combine
   them in compound statements in order to streamline application

Brinckman, et al.        Expires 23 October 2024               [Page 34]
Internet-Draft                    NIPC                        April 2024

   operation against devices, make operations more expediant and
   convenient in one API call.  In principle they do not add any basic
   functionality.  In the OpenAPI model Figure 6 below, we have defined
   a few example extensions, and we will describe them here at a high
   level to provide some context on other possible extensions.

3.2.1.  Write file

   /extension/write/file

   This extension make use of multiple write operations (attribute post)
   to write an entire file to an attribute.  The interface allows the
   application to define the chunk size.

   Operations:

   *  Write file: POST

3.2.2.  Read conditional file

   /extension/read/conditional

   This extension performs a read operation sequentially for a defined
   amount of time until a specified value is read.

   Operations:

   *  Read Conditional: POST

3.2.3.  Bulk

   /extension/bulk

   This extension allows you to create a compound operation made out of
   multiple connection and data operations that are to be executed
   sequentially until they all succeed or there is a failure.  Supported
   operations are:

   *  /extension/connection/create

   *  /extension/connection/delete

   *  /extension/attribute/read

   *  /extension/attribute/write

   *  /extension/attribute/write/file

Brinckman, et al.        Expires 23 October 2024               [Page 35]
Internet-Draft                    NIPC                        April 2024

   *  /extension/attribute/write/blob

   *  /extension/attribute/read/conditional

   Operations:

   *  Bulk: POST

4.  Publish/Subscribe Interface

   The publish/subscribe interface, or data streaming interface, is an
   MQTT publishing interface.  Pub/sub topics can be created and managed
   by means of the /register/topic NIPC element.

   In this memo we propose the data format to be protocol buffers, as
   fully described in the Figure 7 protobuf definition.

5.  Examples

   This section contains a few examples on how applications can leverage
   NIPC operations to communicate with BLE and Zigbee devices.

5.1.  BLE Advertisement

   In this example, we will onboard a device, and setup an advertisement
   subscription topic for that device.

   The sequence of operations for this are:

   *  Onboard a device using the SCIM Interface (out of scope of this
      memo)

   *  Register a topic with the device id to subscribe to advertisements
      POST /register/topic

   *  Subscribe to the topic from the data receiver app MQTT subscribe
      topic

5.2.  BLE Attribute Read/Write

   In this example, we will connect to a BLE device (BLE device does not
   require binding) and read and write from an attribute

   The sequence of operations for this are:

   *  Onboard a device using the SCIM Interface (out of scope of this
      memo)

Brinckman, et al.        Expires 23 October 2024               [Page 36]
Internet-Draft                    NIPC                        April 2024

   *  Connect to the BLE device POST /connectivity/connection

   *  Read an attribute from the BLE device GET /data/attribute

   *  Write to an attribute on the BLE device POST /data/attribute

   *  Disconnect from the BLE device DELETE /connectivity/connection

5.3.  Zigbee Attribute Read/Write

   In this example, we will bind a zigbee device to a Zigbee mesh and
   read and write from an attribute

   The sequence of operations for this are:

   *  Onboard a device using the SCIM Interface (out of scope of this
      memo)

   *  Bind the Zigbee device POST /connectivity/binding

   *  Read an attribute from the Zigbee device GET /data/attribute

   *  Write to an attribute on the Zigbee device POST /data/attribute

   *  Disconnect from the Zigbee device DELETE /connectivity/connection

6.  Security Considerations

   TBD.

7.  IANA Considerations

   TBD.

8.  Normative References

   [BLE53]    Bluetooth SIG, "Bluetooth Core Specification, Version
              5.3", 2021.

   [I-D.shahzad-scim-device-model]
              Shahzad, M., Hassan, H., and E. Lear, "Device Schema
              Extensions to the SCIM model", Work in Progress, Internet-
              Draft, draft-shahzad-scim-device-model-05, 2 June 2023,
              <https://datatracker.ietf.org/doc/html/draft-shahzad-scim-
              device-model-05>.

Brinckman, et al.        Expires 23 October 2024               [Page 37]
Internet-Draft                    NIPC                        April 2024

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119,
              DOI 10.17487/RFC2119, March 1997,
              <https://www.rfc-editor.org/info/rfc2119>.

   [RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
              2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
              May 2017, <https://www.rfc-editor.org/info/rfc8174>.

   [RFC9114]  Bishop, M., Ed., "HTTP/3", RFC 9114, DOI 10.17487/RFC9114,
              June 2022, <https://www.rfc-editor.org/info/rfc9114>.

   [Zigbee22] Connectivity Standards Alliance, "zigbee Specification,
              Version 22 1.0", 2017.

Appendix A.  OpenAPI definition

   The following non-normative model is provide for convenience of the
   implementor.

   <CODE BEGINS> file "openapi.yml"
   openapi: 3.0.3
   info:
     title: Non IP Device Control (NIPC) API
     description: |-
       There has been a large influx of non-IP devices supporting
       processes in manufacturing, healthcare, hospitality, retail, the
       home, and the office.  At the same time, wireless access points
       have been deployed nearly everywhere, many of which have radios
       that can transmit and receive different frame types, such as BLE,
       Zigbee. To integrate multiple of these use cases leveraging a
       single wireless infrastructure and avoid the need for parallel
       infrastructure, a Non IP device gateway function is necessary.
       The gateway provides the following functions:
          - authentication and authorization of application clients that
            will communicate with devices
          - APIs that onboard a device on the network (out of scope for
            this specification, but covered in SCIM for devices)
          - APIs that allow an app to set up a connection with a device
          - APIs that allow an app to exchange data with a device
          - APIs that allow a device to create registrations in the
            network for a device
       These collection of these APIs, in combination with the
       onboarding API (SCIM for devices) will allow an application to
       perform a complete set of operations on Non-IP devices.
     termsOfService: http://swagger.io/terms/
     contact:
       email: bbrinckm@cisco.com

Brinckman, et al.        Expires 23 October 2024               [Page 38]
Internet-Draft                    NIPC                        April 2024

     license:
       name: TBD
       url: TBD
     version: 0.5.3
   externalDocs:
     description: NIPC IETF draft
     url: TBD
   servers:
     - url: https://{gw_host}/nipc
       variables:
         gw_host:
           default: localhost
           description: Gateway Host
   tags:
     - name: connectivity
       description: APIs that allow apps to manage device connections
     - name: data
       description: |-
         APIs that allow apps to exchange data with non-IP devices
     - name: registrations
       description: |-
         APIs that allow apps to make registrations in the network for
         devices.
     - name: extensions
       description: |-
         APIs that simplify application interaciton by implementing one
         or more basic API's into a single API call.

   paths:
   ### Connectivity
     /connectivity/binding:
       post:
         tags:
           - connectivity
         summary: Create a binding for a device id
         description: Create a binding for a device
         operationId: CreateBinding
         requestBody:
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/Object'
             application/xml:
               schema:
                 $ref: '#/components/schemas/Object'
             application/x-www-form-urlencoded:
               schema:
                 $ref: '#/components/schemas/Object'

Brinckman, et al.        Expires 23 October 2024               [Page 39]
Internet-Draft                    NIPC                        April 2024

           required: true
         responses:
           '200':
             description: Success
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/BindingResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/BindingResponse'
           '400':
             description: Bad request
           '401':
             description: Unauthorized
           '405':
             description: Invalid request
           '500':
             description: Server-side failure
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'

       get:
         tags:
           - connectivity
         summary: Get bindings for a device
         description: |-
           Get all bindings control app made (no parameter) or binding
           by object ID, Multiple ids can be provided with comma
           separated strings, or a group id can be provided
         operationId: GetBindings
         parameters:
           - name: id
             in: query
             description: device ids that need to be filtered
             required: false
             explode: true
             schema:
               type: string
               format: uuid
               example: 12345678-1234-5678-1234-56789abcdef4
         responses:
           '200':

Brinckman, et al.        Expires 23 October 2024               [Page 40]
Internet-Draft                    NIPC                        April 2024

             description: Success
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/MultiBindingsResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/MultiBindingsResponse'
           '400':
             description: Bad request
           '401':
             description: Unauthorized
           '405':
             description: Invalid request
           '500':
             description: Server-side failure
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'
       delete:
         tags:
           - connectivity
         summary: |-
           Delete bindings for a device or group of devices
         description: |-
           Delete all bindings control app made or bindings by object
           ID, Multiple ids can be provided with comma separated
           strings, or a group id can be provided
         operationId: DeleteBindings
         parameters:
           - name: id
             in: query
             description: device or group ids that need to be filtered
             required: false
             explode: true
             schema:
               type: string
               format: uuid
               example: 12345678-1234-5678-1234-56789abcdef4
         responses:
           '200':
             description: Success
             content:
               application/json:

Brinckman, et al.        Expires 23 October 2024               [Page 41]
Internet-Draft                    NIPC                        April 2024

                 schema:
                   $ref: '#/components/schemas/SuccessResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/SuccessResponse'
           '400':
             description: Bad request
           '401':
             description: Unauthorized
           '405':
             description: Invalid request
           '500':
             description: Server-side failure
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'

     /connectivity/binding/id/{id}:
       post:
         tags:
           - connectivity
         summary: |-
           Create a binding for a device id (device technology needs to
           support binding)
         description: |-
           Create a binding for a device id, will fail if device has
           multiple technologies defined
         operationId: CreateBindingbyID
         parameters:
           - name: id
             in: path
             description: device or group ids that need to be filtered
             required: true
             schema:
               type: string
               format: uuid
               example: 12345678-1234-5678-1234-56789abcdef4
         responses:
           '200':
             description: Success
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/BindingResponse'

Brinckman, et al.        Expires 23 October 2024               [Page 42]
Internet-Draft                    NIPC                        April 2024

               application/xml:
                 schema:
                   $ref: '#/components/schemas/BindingResponse'
           '400':
             description: Bad request
           '401':
             description: Unauthorized
           '405':
             description: Invalid request
           '500':
             description: Server-side failure
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'

       get:
         tags:
           - connectivity
         summary: Get binding by id for a device
         description: |-
           Get binding by id for a device, success when binding found,
           failure when no binding
         operationId: GetBindingbyId
         parameters:
           - name: id
             in: path
             description: device or group ids that need to be filtered
             required: true
             schema:
               type: string
               format: uuid
               example: 12345678-1234-5678-1234-56789abcdef4
         responses:
           '200':
             description: Success
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/BindingResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/BindingResponse'
           '400':
             description: Bad request

Brinckman, et al.        Expires 23 October 2024               [Page 43]
Internet-Draft                    NIPC                        April 2024

           '401':
             description: Unauthorized
           '405':
             description: Invalid request
           '500':
             description: Server-side failure
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'

       delete:
         tags:
           - connectivity
         summary: Delete binding by id for a device
         description: Delete binding by id for a device
         operationId: DeleteBindingbyID
         parameters:
           - name: id
             in: path
             description: device or group ids that need to be filtered
             required: true
             schema:
               type: string
               format: uuid
               example: 12345678-1234-5678-1234-56789abcdef4
         responses:
           '200':
             description: Success
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/SuccessResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/SuccessResponse'
           '400':
             description: Bad request
           '401':
             description: Unauthorized
           '405':
             description: Invalid request
           '500':
             description: Server-side failure
             content:

Brinckman, et al.        Expires 23 October 2024               [Page 44]
Internet-Draft                    NIPC                        April 2024

               application/json:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'

     /connectivity/connection:
       post:
         tags:
           - connectivity
         summary: |-
           Connect a device to the network, optionally with service
           discovery
         description: |-
           Connect a device to the network, optionally with service
           discovery
         operationId: connConnect
         requestBody:
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/Connection'
             application/xml:
               schema:
                 $ref: '#/components/schemas/Connection'
             application/x-www-form-urlencoded:
               schema:
                 $ref: '#/components/schemas/Connection'
           required: true
         responses:
           '200':
             description: Success
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/ServiceResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/ServiceResponse'
           '400':
             description: Bad request
           '401':
             description: Unauthorized
           '405':
             description: Invalid request
           '500':
             description: Server-side failure

Brinckman, et al.        Expires 23 October 2024               [Page 45]
Internet-Draft                    NIPC                        April 2024

             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'

       get:
         tags:
           - connectivity
         summary: |-
           Get connection state devices for a device or group of
           devices
         description: |-
           Get all connection status for connections made by control ap
           or connection status by object ID, multiple ids can be
           provided with comma separated strings, or a group id can be
           provided
         operationId: GetConnections
         parameters:
           - name: id
             in: query
             description: device or group ids that need to be filtered
             required: false
             explode: true
             schema:
               type: string
               format: uuid
               example: 12345678-1234-5678-1234-56789abcdef4
         responses:
           '200':
             description: Success
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/MultiConnectionsResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/MultiConnectionsResponse'
           '400':
             description: Bad request
           '401':
             description: Unauthorized
           '405':
             description: Invalid request
           '500':
             description: Server-side failure

Brinckman, et al.        Expires 23 October 2024               [Page 46]
Internet-Draft                    NIPC                        April 2024

             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'

       delete:
         tags:
           - connectivity
         summary: Disconnect a device or group of devices
         description: |-
           Disconnect a device or device group by object ID, Multiple
           ids can be provided with comma separated strings, or a
           group id can be provided
         operationId: DeleteConnections
         parameters:
           - name: id
             in: query
             description: device or group ids that need to be filtered
             required: false
             explode: true
             schema:
               type: string
               format: uuid
               example: 12345678-1234-5678-1234-56789abcdef4
         responses:
           '200':
             description: Success
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/SuccessResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/SuccessResponse'
           '400':
             description: Bad request
           '401':
             description: Unauthorized
           '405':
             description: Invalid request
           '500':
             description: Server-side failure
             content:
               application/json:
                 schema:

Brinckman, et al.        Expires 23 October 2024               [Page 47]
Internet-Draft                    NIPC                        April 2024

                   $ref: '#/components/schemas/FailureResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'

     /connectivity/connection/id/{id}:
       post:
         tags:
           - connectivity
         summary: |-
           Connect a device by device id (device technology needs to
           support connection)
         description: |-
           Connect a device by device id, Serivce discovery not
           supported, will fail if device has multiple technologies
           defined.
         operationId: CreateConnectionbyID
         parameters:
           - name: id
             in: path
             description: device or group ids that need to be filtered
             required: true
             schema:
               type: string
               format: uuid
               example: 12345678-1234-5678-1234-56789abcdef4
         responses:
           '200':
             description: Success
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/SuccessResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/SuccessResponse'
           '400':
             description: Bad request
           '401':
             description: Unauthorized
           '405':
             description: Invalid request
           '500':
             description: Server-side failure
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'

Brinckman, et al.        Expires 23 October 2024               [Page 48]
Internet-Draft                    NIPC                        April 2024

               application/xml:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'

       get:
         tags:
           - connectivity
         summary: Get connection by id for a device
         description: |-
           Get connection by id for a device, success when device
           connected, failure when device not connected
         operationId: GetConnectionbyId
         parameters:
           - name: id
             in: path
             description: device or group ids that need to be filtered
             required: true
             schema:
               type: string
               format: uuid
               example: 12345678-1234-5678-1234-56789abcdef4
         responses:
           '200':
             description: Success
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/SuccessResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/SuccessResponse'
           '400':
             description: Bad request
           '401':
             description: Unauthorized
           '405':
             description: Invalid request
           '500':
             description: Server-side failure
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'

       delete:

Brinckman, et al.        Expires 23 October 2024               [Page 49]
Internet-Draft                    NIPC                        April 2024

         tags:
           - connectivity
         summary: Delete connection by id for a device
         description: Disconnect a device by id
         operationId: DeleteConnectionbyID
         parameters:
           - name: id
             in: path
             description: device or group ids that need to be filtered
             required: true
             schema:
               type: string
               format: uuid
               example: 12345678-1234-5678-1234-56789abcdef4
         responses:
           '200':
             description: Success
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/SuccessResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/SuccessResponse'
           '400':
             description: Bad request
           '401':
             description: Unauthorized
           '405':
             description: Invalid request
           '500':
             description: Server-side failure
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'

     /connectivity/services:
       get:
         tags:
           - connectivity
         summary: Discover services on a device
         description: Discover services on a device
         operationId: ServiceDiscovey
         parameters:

Brinckman, et al.        Expires 23 October 2024               [Page 50]
Internet-Draft                    NIPC                        April 2024

         - name: Service
           in: query
           description: Services to discover
           required: true
           schema:
             $ref: '#/components/schemas/Service'
         responses:
           '200':
             description: Success
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/ServiceResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/ServiceResponse'
           '400':
             description: Bad request
           '401':
             description: Unauthorized
           '405':
             description: Invalid request
           '500':
             description: Server-side failure
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'

     /connectivity/services/id/{id}:
       get:
         tags:
           - connectivity
         summary: Get services by id for a device
         description: |-
           Get services by id for a connected device, success when
           device connected, failure when device not connected
         operationId: GetServicesbyId
         parameters:
           - name: id
             in: path
             description: device or group ids that need to be filtered
             required: true
             schema:
               type: string
               format: uuid
               example: 12345678-1234-5678-1234-56789abcdef4
         responses:

Brinckman, et al.        Expires 23 October 2024               [Page 51]
Internet-Draft                    NIPC                        April 2024

           '200':
             description: Success
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/ServiceResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/ServiceResponse'
           '400':
             description: Bad request
           '401':
             description: Unauthorized
           '405':
             description: Invalid request
           '500':
             description: Server-side failure
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'

   ### Data
     /data/attribute:
       post:
         tags:
           - data
         summary: Write a value to an attribute on a device
         description: Write a value to an attribute on a device
         operationId: dataWrite
         requestBody:
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/AttributeValue'
             application/xml:
               schema:
                 $ref: '#/components/schemas/AttributeValue'
             application/x-www-form-urlencoded:
               schema:
                 $ref: '#/components/schemas/AttributeValue'
           required: true
         responses:
           '200':
             description: Success

Brinckman, et al.        Expires 23 October 2024               [Page 52]
Internet-Draft                    NIPC                        April 2024

             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/AttributeValueResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/AttributeValueResponse'
           '400':
             description: Bad request
           '401':
             description: Unauthorized
           '405':
             description: Invalid request
           '500':
             description: Server-side failure
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'

       put:
         tags:
           - data
         summary: Update a value of an attribute on a device
         description: Update a value of an attribute on a device
         operationId: dataUpdate
         requestBody:
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/AttributeValue'
             application/xml:
               schema:
                 $ref: '#/components/schemas/AttributeValue'
             application/x-www-form-urlencoded:
               schema:
                 $ref: '#/components/schemas/AttributeValue'
           required: true
         responses:
           '200':
             description: Success
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/AttributeValueResponse'

Brinckman, et al.        Expires 23 October 2024               [Page 53]
Internet-Draft                    NIPC                        April 2024

               application/xml:
                 schema:
                   $ref: '#/components/schemas/AttributeValueResponse'
           '400':
             description: Bad request
           '401':
             description: Unauthorized
           '405':
             description: Invalid request
           '500':
             description: Server-side failure
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'

       delete:
         tags:
           - data
         summary: Delete a value from an attribute on a device
         description: Delete a value to an attribute on a device
         operationId: dataDelete
         parameters:
         - name: attribute
           in: query
           description: attributes of a given device
           required: true
           schema:
             $ref: '#/components/schemas/Attribute'
         responses:
           '200':
             description: Success
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/AttributeValueResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/AttributeValueResponse'
           '400':
             description: Bad request
           '401':
             description: Unauthorized
           '405':
             description: Invalid request

Brinckman, et al.        Expires 23 October 2024               [Page 54]
Internet-Draft                    NIPC                        April 2024

           '500':
             description: Server-side failure
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'

       get:
         tags:
           - data
         summary: Read a value from an attribute on a device
         description: Read a value to an attribute on a device
         operationId: dataRead
         parameters:
         - name: attribute
           in: query
           description: attributes of a given device
           required: true
           schema:
             $ref: '#/components/schemas/Attribute'
         responses:
           '200':
             description: Success
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/AttributeValueResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/AttributeValueResponse'
           '400':
             description: Bad request
           '401':
             description: Unauthorized
           '405':
             description: Invalid request
           '500':
             description: Server-side failure
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'

Brinckman, et al.        Expires 23 October 2024               [Page 55]
Internet-Draft                    NIPC                        April 2024

     /data/subscription:
       post:
         tags:
           - data
         summary: |-
            Subscribe to streaming data from an attribute on a device
         description: |-
           Subscribe to streaming data from an attribute on a device
         operationId: dataSubscribe
         requestBody:
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/Subscription'
             application/xml:
               schema:
                 $ref: '#/components/schemas/Subscription'
             application/x-www-form-urlencoded:
               schema:
                 $ref: '#/components/schemas/Subscription'
           required: true
         responses:
           '200':
             description: Success
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/SuccessResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/SuccessResponse'
           '400':
             description: Bad request
           '401':
             description: Unauthorized
           '405':
             description: Invalid request
           '500':
             description: Server-side failure
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'

       put:

Brinckman, et al.        Expires 23 October 2024               [Page 56]
Internet-Draft                    NIPC                        April 2024

         tags:
           - data
         summary: |-
           update streaming data subscription from an attribute on a
           device
         description: |-
           update streaming data subscription from an attribute on a
           device
         operationId: dataUpdateSubscribe
         requestBody:
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/Subscription'
             application/xml:
               schema:
                 $ref: '#/components/schemas/Subscription'
             application/x-www-form-urlencoded:
               schema:
                 $ref: '#/components/schemas/Subscription'
           required: true
         responses:
           '200':
             description: Success
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/SuccessResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/SuccessResponse'
           '400':
             description: Bad request
           '401':
             description: Unauthorized
           '405':
             description: Invalid request
           '500':
             description: Server-side failure
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'

       delete:

Brinckman, et al.        Expires 23 October 2024               [Page 57]
Internet-Draft                    NIPC                        April 2024

         tags:
           - data
         summary: |-
           Unsubscribe to streaming data from an attribute on a device
         description: |-
           Unsubscribe to streaming data from an attribute on a device
         operationId: dataUnsubscribe
         parameters:
         - name: subscription
           in: query
           description: subscription on a device
           required: true
           schema:
             $ref: '#/components/schemas/Subscription'
         responses:
           '200':
             description: Success
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/SuccessResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/SuccessResponse'
           '400':
             description: Bad request
           '401':
             description: Unauthorized
           '405':
             description: Invalid request
           '500':
             description: Server-side failure
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'

       get:
         tags:
           - data
         summary: Get the status of a subscription on a device
         description: Get the status of a subscription on a device
         operationId: dataGetSubscription
         parameters:
         - name: subscription

Brinckman, et al.        Expires 23 October 2024               [Page 58]
Internet-Draft                    NIPC                        April 2024

           in: query
           description: subscription on a device
           required: true
           schema:
             $ref: '#/components/schemas/Subscription'
         responses:
           '200':
             description: Success
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/SuccessResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/SuccessResponse'
           '400':
             description: Bad request
           '401':
             description: Unauthorized
           '405':
             description: Invalid request
           '500':
             description: Server-side failure
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'

     /data/subscription/topic/{topic}:
       delete:
         tags:
           - data
         summary: delete all active subscriptions by topic
         description: delete all active subscriptions by topic
         operationId: deleteSubscriptionbyTopic
         parameters:
           - name: topic
             in: path
             description: topic that needs to be filtered
             required: true
             schema:
               type: string
               example: "enterprise/hospital/pulse_oximeter"
         responses:
           '200':

Brinckman, et al.        Expires 23 October 2024               [Page 59]
Internet-Draft                    NIPC                        April 2024

             description: Success
             content:
               application/json:
                 schema:
                   $ref:
                      '#/components/schemas/MultiSubscriptionResponse'
               application/xml:
                 schema:
                   $ref:
                      '#/components/schemas/MultiSubscriptionResponse'
           '400':
             description: Bad request
           '401':
             description: Unauthorized
           '405':
             description: Invalid request
           '500':
             description: Server-side failure
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'

       get:
         tags:
           - data
         summary: get all active subscriptions by topic
         description: get all active subscriptions by topic
         operationId: getSubsciptionsbyTopic
         parameters:
           - name: topic
             in: path
             description: topic that needs to be filtered
             required: true
             schema:
               type: string
               example: "enterprise/hospital/pulse_oximeter"
         responses:
           '200':
             description: Success
             content:
               application/json:
                 schema:
                   $ref:
                      '#/components/schemas/MultiSubscriptionResponse'

Brinckman, et al.        Expires 23 October 2024               [Page 60]
Internet-Draft                    NIPC                        April 2024

               application/xml:
                 schema:
                   $ref:
                      '#/components/schemas/MultiSubscriptionResponse'
           '400':
             description: Bad request
           '401':
             description: Unauthorized
           '405':
             description: Invalid request
           '500':
             description: Server-side failure
             content:
               application/json:
                 schema:
                   $ref:
                      '#/components/schemas/MultiSubscriptionResponse'
               application/xml:
                 schema:
                   $ref:
                      '#/components/schemas/MultiSubscriptionResponse'

     /data/subscription/id/{id}:
       delete:
         tags:
           - data
         summary: delete all subscriptions by id
         description: delete all subscriptions by id
         operationId: deleteSubscriptionbyID
         parameters:
           - name: id
             in: path
             description: object id that needs to be filtered
             required: true
             schema:
               type: string
               example: 12345678-1234-5678-1234-56789abcdef4
         responses:
           '200':
             description: Success
             content:
               application/json:
                 schema:
                   $ref:
                      '#/components/schemas/MultiSubscriptionResponse'
               application/xml:
                 schema:
                   $ref:

Brinckman, et al.        Expires 23 October 2024               [Page 61]
Internet-Draft                    NIPC                        April 2024

                      '#/components/schemas/MultiSubscriptionResponse'
           '400':
             description: Bad request
           '401':
             description: Unauthorized
           '405':
             description: Invalid request
           '500':
             description: Server-side failure
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'

       get:
         tags:
           - data
         summary: get all subscriptions by object id
         description: get all subscriptions by object id
         operationId: getSubscriptionbyID
         parameters:
           - name: id
             in: path
             description: object id that needs to be filtered
             required: true
             schema:
               type: string
               example: 12345678-1234-5678-1234-56789abcdef4
         responses:
           '200':
             description: Success
             content:
               application/json:
                 schema:
                   $ref:
                      '#/components/schemas/MultiSubscriptionResponse'
               application/xml:
                 schema:
                   $ref:
                      '#/components/schemas/MultiSubscriptionResponse'
           '400':
             description: Bad request
           '401':
             description: Unauthorized
           '405':

Brinckman, et al.        Expires 23 October 2024               [Page 62]
Internet-Draft                    NIPC                        April 2024

             description: Invalid request
           '500':
             description: Server-side failure
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'

     /data/broadcast:
       post:
         tags:
           - data
         summary: Broadcast to a device
         description: Broadcast to a device
         operationId: dataBroadcast
         requestBody:
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/Broadcast'
             application/xml:
               schema:
                 $ref: '#/components/schemas/Broadcast'
             application/x-www-form-urlencoded:
               schema:
                 $ref: '#/components/schemas/Broadcast'
           required: true
         responses:
           '200':
             description: Success
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/SuccessResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/SuccessResponse'
           '400':
             description: Bad request
           '401':
             description: Unauthorized
           '405':
             description: Invalid request
           '500':
             description: Server-side failure

Brinckman, et al.        Expires 23 October 2024               [Page 63]
Internet-Draft                    NIPC                        April 2024

             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'

   ### Registrations
     /registration/topic:
       post:
         tags:
           - registrations
         summary: Register a publish/subscribe topic
         description: Register a publish/subscribe topic
         operationId: registerTopic
         requestBody:
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/Topic'
             application/xml:
               schema:
                 $ref: '#/components/schemas/Topic'
             application/x-www-form-urlencoded:
               schema:
                 $ref: '#/components/schemas/Topic'
           required: true
         responses:
           '200':
             description: Success
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/TopicResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/TopicResponse'
           '400':
             description: Bad request
           '401':
             description: Unauthorized
           '405':
             description: Invalid request
           '500':
             description: Server-side failure
             content:
               application/json:

Brinckman, et al.        Expires 23 October 2024               [Page 64]
Internet-Draft                    NIPC                        April 2024

                 schema:
                   $ref: '#/components/schemas/FailureResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'

       put:
         tags:
           - registrations
         summary: Update a publish/subscribe topic
         description: Update a publish/subscribe topic
         operationId: UpdateTopic
         requestBody:
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/Topic'
             application/xml:
               schema:
                 $ref: '#/components/schemas/Topic'
             application/x-www-form-urlencoded:
               schema:
                 $ref: '#/components/schemas/Topic'
           required: true
         responses:
           '200':
             description: Success
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/TopicResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/TopicResponse'
           '400':
             description: Bad request
           '401':
             description: Unauthorized
           '405':
             description: Invalid request
           '500':
             description: Server-side failure
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'
               application/xml:
                 schema:

Brinckman, et al.        Expires 23 October 2024               [Page 65]
Internet-Draft                    NIPC                        April 2024

                   $ref: '#/components/schemas/FailureResponse'

       delete:
         tags:
           - registrations
         summary: unregister a publish/subscribe topic
         description: |-
           unregister a publish/subscribe topic, Multiple topics can
           be provided with comma separate strings, or a group id can
           be provided.
         operationId: unregisterTopic
         parameters:
           - name: topic
             in: query
             description: topic that need to be filtered
             required: false
             explode: true
             schema:
               type: string
               example: "enterprise/hospital/pulse_oximeter"
         responses:
           '200':
             description: Success
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/MultiTopicsResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/MultiTopicsResponse'
           '400':
             description: Bad request
           '401':
             description: Unauthorized
           '405':
             description: Invalid request
           '500':
             description: Server-side failure
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'

       get:
         tags:

Brinckman, et al.        Expires 23 October 2024               [Page 66]
Internet-Draft                    NIPC                        April 2024

           - registrations
         summary: get one or multiple publish/subscribe topic
         description: |-
           unregister a publish/subscribe topic, Multiple topics can be
           provided with comma separate strings, or a group id can be
           provided
         operationId: getTopic
         parameters:
           - name: topic
             in: query
             description: topic that need to be filtered
             required: false
             explode: true
             schema:
               type: string
               example: "enterprise/hospital/pulse_oximeter"
         responses:
           '200':
             description: Success
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/MultiTopicsResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/MultiTopicsResponse'
           '400':
             description: Bad request
           '401':
             description: Unauthorized
           '405':
             description: Invalid request
           '500':
             description: Server-side failure
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'

     /registration/topic/{topic}:
       delete:
         tags:
           - registrations
         summary: delete a publish/subscribe topic by name
         description: unregister a publish/subscribe topic by Name

Brinckman, et al.        Expires 23 October 2024               [Page 67]
Internet-Draft                    NIPC                        April 2024

         operationId: deleteTopicbyName
         parameters:
           - name: topic
             in: path
             description: topic that needs to be filtered
             required: true
             schema:
               type: string
               example: "enterprise/hospital/pulse_oximeter"
         responses:
           '200':
             description: Success
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/TopicResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/TopicResponse'
           '400':
             description: Bad request
           '401':
             description: Unauthorized
           '405':
             description: Invalid request
           '500':
             description: Server-side failure
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'

       get:
         tags:
           - registrations
         summary: get a publish/subscribe topic by name
         description: get a publish/subscribe topic by name
         operationId: getTopicbyName
         parameters:
           - name: topic
             in: path
             description: topic that needs to be filtered
             required: true
             schema:
               type: string

Brinckman, et al.        Expires 23 October 2024               [Page 68]
Internet-Draft                    NIPC                        April 2024

               example: "enterprise/hospital/pulse_oximeter"
         responses:
           '200':
             description: Success
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/TopicResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/TopicResponse'
           '400':
             description: Bad request
           '401':
             description: Unauthorized
           '405':
             description: Invalid request
           '500':
             description: Server-side failure
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'

     /registration/topic/data-app/{data-app}:
       delete:
         tags:
           - registrations
         summary: delete all publish/subscribe topics by data-app
         description: |-
           unregister all publish/subscribe topics by data-app
         operationId: deleteTopicbyDataApp
         parameters:
           - name: data-app
             in: path
             description: data app that needs to be filtered
             required: true
             schema:
               type: string
               example: https://data-app-1
         responses:
           '200':
             description: Success
             content:
               application/json:

Brinckman, et al.        Expires 23 October 2024               [Page 69]
Internet-Draft                    NIPC                        April 2024

                 schema:
                   $ref: '#/components/schemas/MultiTopicsResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/MultiTopicsResponse'
           '400':
             description: Bad request
           '401':
             description: Unauthorized
           '405':
             description: Invalid request
           '500':
             description: Server-side failure
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'

       get:
         tags:
           - registrations
         summary: get all publish/subscribe topics by data-app
         description: get all publish/subscribe topics by data-app
         operationId: getTopicbyDataApp
         parameters:
           - name: data-app
             in: path
             description: data app that needs to be filtered
             required: true
             schema:
               type: string
               example: https://data-app-1
         responses:
           '200':
             description: Success
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/MultiTopicsResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/MultiTopicsResponse'
           '400':
             description: Bad request
           '401':

Brinckman, et al.        Expires 23 October 2024               [Page 70]
Internet-Draft                    NIPC                        April 2024

             description: Unauthorized
           '405':
             description: Invalid request
           '500':
             description: Server-side failure
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'

     /registration/topic/id/{id}:
       delete:
         tags:
           - registrations
         summary: delete all publish/subscribe topics by object id
         description: unregister all publish/subscribe topics by id
         operationId: deleteTopicbyID
         parameters:
           - name: id
             in: path
             description: object id that needs to be filtered
             required: true
             schema:
               type: string
               example: 12345678-1234-5678-1234-56789abcdef4
         responses:
           '200':
             description: Success
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/MultiTopicsResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/MultiTopicsResponse'
           '400':
             description: Bad request
           '401':
             description: Unauthorized
           '405':
             description: Invalid request
           '500':
             description: Server-side failure
             content:
               application/json:

Brinckman, et al.        Expires 23 October 2024               [Page 71]
Internet-Draft                    NIPC                        April 2024

                 schema:
                   $ref: '#/components/schemas/FailureResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'

       get:
         tags:
           - registrations
         summary: get all publish/subscribe topics by object id
         description: get all publish/subscribe topics by object id
         operationId: getTopicbyID
         parameters:
           - name: id
             in: path
             description: object id that needs to be filtered
             required: true
             schema:
               type: string
               example: 12345678-1234-5678-1234-56789abcdef4
         responses:
           '200':
             description: Success
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/MultiTopicsResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/MultiTopicsResponse'
           '400':
             description: Bad request
           '401':
             description: Unauthorized
           '405':
             description: Invalid request
           '500':
             description: Server-side failure
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'

     /registration/file:
       post:

Brinckman, et al.        Expires 23 October 2024               [Page 72]
Internet-Draft                    NIPC                        April 2024

         tags:
           - registrations
         summary: Register and upload a file for later use
         description: Register and upload a file for later use
         operationId: registerFile
         requestBody:
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/File'
             application/xml:
               schema:
                 $ref: '#/components/schemas/File'
             application/x-www-form-urlencoded:
               schema:
                 $ref: '#/components/schemas/File'
           required: true
         responses:
           '200':
             description: Success
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/SuccessResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/SuccessResponse'
           '400':
             description: Bad request
           '401':
             description: Unauthorized
           '405':
             description: Invalid request
           '500':
             description: Server-side failure
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'

       put:
         tags:
           - registrations
         summary: Update an existing file registration
         description: Update an existing file registration

Brinckman, et al.        Expires 23 October 2024               [Page 73]
Internet-Draft                    NIPC                        April 2024

         operationId: UpdateFile
         requestBody:
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/File'
             application/xml:
               schema:
                 $ref: '#/components/schemas/File'
             application/x-www-form-urlencoded:
               schema:
                 $ref: '#/components/schemas/File'
           required: true
         responses:
           '200':
             description: Success
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/SuccessResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/SuccessResponse'
           '400':
             description: Bad request
           '401':
             description: Unauthorized
           '405':
             description: Invalid request
           '500':
             description: Server-side failure
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'

       delete:
         tags:
           - registrations
         summary: Delete a file
         description: Delete a file
         operationId: DeleteFile
         parameters:
           - name: filename
             in: query

Brinckman, et al.        Expires 23 October 2024               [Page 74]
Internet-Draft                    NIPC                        April 2024

             description: file that needs to be filtered
             required: false
             explode: true
             schema:
               type: string
               example: "firmware.dat"
         responses:
           '200':
             description: Success
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/SuccessResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/SuccessResponse'
           '400':
             description: Bad request
           '401':
             description: Unauthorized
           '405':
             description: Invalid request
           '500':
             description: Server-side failure
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'

       get:
         tags:
           - registrations
         summary: get a file
         description: |-
           get a file by name of get all files if no names
           supplied.
         operationId: getFile
         parameters:
           - name: filename
             in: query
             description: file that needs to be filtered
             required: false
             explode: true
             schema:
               type: string

Brinckman, et al.        Expires 23 October 2024               [Page 75]
Internet-Draft                    NIPC                        April 2024

               example: "firmware.dat"
         responses:
           '200':
             description: Success
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/MultiFileResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/MultiFileResponse'
           '400':
             description: Bad request
           '401':
             description: Unauthorized
           '405':
             description: Invalid request
           '500':
             description: Server-side failure
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'

     /registration/file/{filename}:
       delete:
         tags:
           - registrations
         summary: delete a file by name
         description: delete a file by name
         operationId: deleteFilebyName
         parameters:
           - name: filename
             in: path
             description: file that needs to be filtered
             required: true
             schema:
               type: string
               example: "firmware.dat"
         responses:
           '200':
             description: Success
             content:
               application/json:
                 schema:

Brinckman, et al.        Expires 23 October 2024               [Page 76]
Internet-Draft                    NIPC                        April 2024

                   $ref: '#/components/schemas/FileResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/FileResponse'
           '400':
             description: Bad request
           '401':
             description: Unauthorized
           '405':
             description: Invalid request
           '500':
             description: Server-side failure
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'

       get:
         tags:
           - registrations
         summary: get a file by name
         description: get a file by name
         operationId: getFilebyName
         parameters:
           - name: filename
             in: path
             description: file that needs to be filtered
             required: true
             schema:
               type: string
               example: 12345678-1234-5678-1234-56789abcdef4
         responses:
           '200':
             description: Success
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/FileResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/FileResponse'
           '400':
             description: Bad request
           '401':
             description: Unauthorized

Brinckman, et al.        Expires 23 October 2024               [Page 77]
Internet-Draft                    NIPC                        April 2024

           '405':
             description: Invalid request
           '500':
             description: Server-side failure
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'

   ### Extensions
     /extension/connection/create:
       post:
         tags:
           - extensions
         summary: |-
           Connect a device to the network, optionally with service
           discovery
         description: |-
           Connect a device to the network, optionally with service
           discovery
         operationId: ExtConnect
         requestBody:
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/Connection'
             application/xml:
               schema:
                 $ref: '#/components/schemas/Connection'
             application/x-www-form-urlencoded:
               schema:
                 $ref: '#/components/schemas/Connection'
           required: true
         responses:
           '200':
             description: Success
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/ServiceResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/ServiceResponse'
           '400':
             description: Bad request

Brinckman, et al.        Expires 23 October 2024               [Page 78]
Internet-Draft                    NIPC                        April 2024

           '401':
             description: Unauthorized
           '405':
             description: Invalid request
           '500':
             description: Server-side failure
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'

     /extension/connection/delete:
       post:
         tags:
           - extensions
         summary: |-
           Connect a device to the network, optionally with service
           discovery
         description: |-
           Connect a device to the network, optionally with service
           discovery
         operationId: ExtDisconnect
         requestBody:
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/Object'
             application/xml:
               schema:
                 $ref: '#/components/schemas/Object'
             application/x-www-form-urlencoded:
               schema:
                 $ref: '#/components/schemas/Object'
           required: true
         responses:
           '200':
             description: Success
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/SuccessResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/SuccessResponse'
           '400':

Brinckman, et al.        Expires 23 October 2024               [Page 79]
Internet-Draft                    NIPC                        April 2024

             description: Bad request
           '401':
             description: Unauthorized
           '405':
             description: Invalid request
           '500':
             description: Server-side failure
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'

     /extension/attribute/write:
       post:
         tags:
           - extensions
         summary: Write a value to an attribute on a device
         description: Write a value to an attribute on a device
         operationId: dataAttrWrite
         requestBody:
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/AttributeValue'
             application/xml:
               schema:
                 $ref: '#/components/schemas/AttributeValue'
             application/x-www-form-urlencoded:
               schema:
                 $ref: '#/components/schemas/AttributeValue'
           required: true
         responses:
           '200':
             description: Success
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/AttributeValueResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/AttributeValueResponse'
           '400':
             description: Bad request
           '401':
             description: Unauthorized

Brinckman, et al.        Expires 23 October 2024               [Page 80]
Internet-Draft                    NIPC                        April 2024

           '405':
             description: Invalid request
           '500':
             description: Server-side failure
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'

     /extension/attribute/write/file:
       post:
         tags:
           - extensions
         summary: Write a file to an attribute across multiple writes
         description: |-
           Write a file to an attribute across multiple writes
         operationId: dataWriteFile
         requestBody:
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/AttributeFile'
             application/xml:
               schema:
                 $ref: '#/components/schemas/AttributeFile'
             application/x-www-form-urlencoded:
               schema:
                 $ref: '#/components/schemas/AttributeFile'
           required: true
         responses:
           '200':
             description: Success
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/SuccessResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/SuccessResponse'
           '400':
             description: Bad request
           '401':
             description: Unauthorized
           '405':
             description: Invalid request

Brinckman, et al.        Expires 23 October 2024               [Page 81]
Internet-Draft                    NIPC                        April 2024

           '500':
             description: Server-side failure
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'

     /extension/attribute/write/blob:
       post:
         tags:
           - extensions
         summary: |-
           Write a binary blob to an attribute across multiple writes
         description: |-
           Write a binary blob to an attribute across multiple writes
         operationId: dataWriteBlob
         requestBody:
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/AttributeBlob'
             application/xml:
               schema:
                 $ref: '#/components/schemas/AttributeBlob'
             application/x-www-form-urlencoded:
               schema:
                 $ref: '#/components/schemas/AttributeBlob'
           required: true
         responses:
           '200':
             description: Success
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/SuccessResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/SuccessResponse'
           '400':
             description: Bad request
           '401':
             description: Unauthorized
           '405':
             description: Invalid request
           '500':

Brinckman, et al.        Expires 23 October 2024               [Page 82]
Internet-Draft                    NIPC                        April 2024

             description: Server-side failure
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'

     /extension/attribute/read:
       post:
         tags:
           - extensions
         summary: Read an attribute on a device
         description: Write a value to an attribute on a device
         operationId: dataAttrRead
         requestBody:
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/Attribute'
             application/xml:
               schema:
                 $ref: '#/components/schemas/Attribute'
             application/x-www-form-urlencoded:
               schema:
                 $ref: '#/components/schemas/Attribute'
           required: true
         responses:
           '200':
             description: Success
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/AttributeValueResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/AttributeValueResponse'
           '400':
             description: Bad request
           '401':
             description: Unauthorized
           '405':
             description: Invalid request
           '500':
             description: Server-side failure
             content:
               application/json:

Brinckman, et al.        Expires 23 October 2024               [Page 83]
Internet-Draft                    NIPC                        April 2024

                 schema:
                   $ref: '#/components/schemas/FailureResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'

     /extension/attribute/read/conditional:
       post:
         tags:
           - extensions
         summary: |-
           Read a value from attribute on a device until it matches a
           specific value.
         description: |-
           Read a value from attribute on a device until it matches a
           specific value.
         operationId: dataReadCond
         requestBody:
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/AttributeConditional'
             application/xml:
               schema:
                 $ref: '#/components/schemas/AttributeConditional'
             application/x-www-form-urlencoded:
               schema:
                 $ref: '#/components/schemas/AttributeConditional'
           required: true
         responses:
           '200':
             description: Success
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/AttributeValueResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/AttributeValueResponse'
           '400':
             description: Bad request
           '401':
             description: Unauthorized
           '405':
             description: Invalid request
           '500':
             description: Server-side failure
             content:

Brinckman, et al.        Expires 23 October 2024               [Page 84]
Internet-Draft                    NIPC                        April 2024

               application/json:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'

     /extension/bulk:
       post:
         tags:
           - extensions
         summary: Compound operations on a device
         description: Compound operations on a device
         operationId: Bulk
         requestBody:
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/Bulk'
             application/xml:
               schema:
                 $ref: '#/components/schemas/Bulk'
             application/x-www-form-urlencoded:
               schema:
                 $ref: '#/components/schemas/Bulk'
           required: true
         responses:
           '200':
             description: Success
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/BulkResponse'
               application/xml:
                 schema:
                   $ref: '#/components/schemas/BulkResponse'
           '400':
             description: Bad request
           '401':
             description: Unauthorized
           '405':
             description: Invalid request
           '500':
             description: Server-side failure
             content:
               application/json:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'

Brinckman, et al.        Expires 23 October 2024               [Page 85]
Internet-Draft                    NIPC                        April 2024

               application/xml:
                 schema:
                   $ref: '#/components/schemas/FailureResponse'

   components:
     schemas:
   # BLE objects
   ##  An array for BLE services
       BLEServiceslist:
         required:
           - services
         type: object
         properties:
           services:
             type: array
             xml:
               name: services
               wrapped: true
             items:
               $ref: '#/components/schemas/BLEService'
         xml:
           name: BLEServiceslist

   ## A BLE service with its characteristics
       BLEService:
         required:
           - serviceID
           - characteristics
         type: object
         properties:
           serviceID:
             type: string
             format: uuid
             example: 12345678-1234-5678-1234-56789abcdef4
           characteristics:
             type: array
             xml:
               name: characteristics
               wrapped: true
             items:
               $ref: '#/components/schemas/BLECharacteristic'
         xml:
           name: BLEService

   ## A BLE characteristics with its descriptors
       BLECharacteristic:
         required:
           - characteristicID

Brinckman, et al.        Expires 23 October 2024               [Page 86]
Internet-Draft                    NIPC                        April 2024

           - flags
           - descriptors
         type: object
         properties:
           characteristicID:
             type: string
             format: uuid
             example: 12345678-1234-5678-1234-56789abcdef4
           flags:
             type: array
             example:
             - read
             - write
             items:
               type: string
               enum:
                 - read
                 - write
                 - notify
           descriptors:
             type: array
             xml:
               name: descriptors
               wrapped: true
             items:
               $ref: '#/components/schemas/BLEDescriptor'
         xml:
           name: BLECharacteristic

   ## A BLE descriptor
       BLEDescriptor:
         required:
           - descriptorID
         type: object
         properties:
           descriptorID:
             type: string
             format: uuid
             example: 12345678-1234-5678-1234-56789abcdef4
         xml:
           name: BLEDescriptor

   ## BLE service ID only
       BLEServiceID:
         type: object
         properties:
           serviceID:
             type: string

Brinckman, et al.        Expires 23 October 2024               [Page 87]
Internet-Draft                    NIPC                        April 2024

             format: uuid
             example: 12345678-1234-5678-1234-56789abcdef4
         xml:
           name: BLEServiceID

   ## Attributes that define a BLE attribute
       BLEAttributes:
         required:
           - ble
         type: object
         properties:
           ble:
             required:
               - serviceID
               - characteristicID
             type: object
             properties:
               serviceID:
                 type: string
                 format: uuid
                 example: 12345678-1234-5678-1234-56789abcdef4
               characteristicID:
                 type: string
                 format: uuid
                 example: 12345678-1234-5678-1234-56789abcdef4
               long:
                 type: boolean
                 example: false
         xml:
           name: BLEAttributes

   ## Defines different types of BLE topics
       BLETopic:
         required:
           - ble
         type: object
         properties:
           ble:
             oneOf:
               - $ref: '#/components/schemas/BLESubTopic'
               - $ref: '#/components/schemas/BLEConnTopic'
               - $ref: '#/components/schemas/BLEAdvTopic'
         xml:
           name: BLETopic

   ## BLE Gatt Topic definition
       BLESubTopic:
         required:

Brinckman, et al.        Expires 23 October 2024               [Page 88]
Internet-Draft                    NIPC                        April 2024

           - type
           - serviceID
           - characteristicID
         type: object
         properties:
           type:
             type: string
             example: gatt
             enum:
               - gatt
           serviceID:
             type: string
             example: 12345678-1234-5678-1234-56789abcdef0
           characteristicID:
             type: string
             example: 12345678-1234-5678-1234-56789abcdef1
         xml:
           name: BLESubTopic

   ## BLE Connection event Topic definition
       BLEConnTopic:
         required:
           - type
         type: object
         properties:
           type:
             type: string
             example: connection_events
             enum:
               - connection_events
         xml:
           name: BLEConnTopic

   ## BLE Advertisement Topic definition
       BLEAdvTopic:
         required:
           - type
         type: object
         properties:
           type:
             type: string
             example: advertisements
             enum:
               - advertisements
           filterType:
             type: string
             example: deny
             enum:

Brinckman, et al.        Expires 23 October 2024               [Page 89]
Internet-Draft                    NIPC                        April 2024

               - deny
               - allow
           filters:
             type: array
             xml:
               name: filters
               wrapped: true
             items:
               $ref: '#/components/schemas/BLEAdvertisement'
         xml:
           name: BLEAdvTopic

   ## BLE Advertisement attributes
       BLEAdvertisement:
         type: object
         properties:
           adTtype:
             type: string
             format: byte
             example: ff
           adData:
             type: string
             format: byte
             example: 4c00*
         xml:
           name: BLEAdvertisement

   ## Attributes that define a BLE broadcast
       BLEBroadcast:
         required:
           - ble
         type: object
         properties:
           ble:
             required:
               - advertisement
             type: array
             xml:
               name: services
               wrapped: true
             items:
               $ref: '#/components/schemas/BLEAdvertisement'
         xml:
           name: BLEBroadcast

   # Zigbee objects
   ## An array for Zigbee Endpoints
       ZigbeeEndpointlist:

Brinckman, et al.        Expires 23 October 2024               [Page 90]
Internet-Draft                    NIPC                        April 2024

         required:
           - endpoints
         type: object
         properties:
           endpoints:
             type: array
             xml:
               name: endpoints
               wrapped: true
             items:
               $ref: '#/components/schemas/ZigbeeEndpoint'
         xml:
           name: ZigbeeEndpointlist

   ## A Zigbee endpoint with its clusters
       ZigbeeEndpoint:
         required:
           - endpointID
           - clusters
         type: object
         properties:
           endpointID:
             type: integer
             format: int32
             example: 10
           clusters:
             type: array
             xml:
               name: clusters
               wrapped: true
             items:
               $ref: '#/components/schemas/ZigbeeCluster'
         xml:
           name: ZigbeeEndpoint

   ## A Zigbee cluster with its attributes
       ZigbeeCluster:
         required:
           - clusterID
           - attributes
         type: object
         properties:
           clusterID:
             type: integer
             format: int32
             example: 0
           attributes:
             type: array

Brinckman, et al.        Expires 23 October 2024               [Page 91]
Internet-Draft                    NIPC                        April 2024

             xml:
               name: attributes
               wrapped: true
             items:
               $ref: '#/components/schemas/ZigbeeAttribute'
         xml:
           name: ZigbeeCluster

   ## A Zigbee attribute
       ZigbeeAttribute:
         required:
           - attributeID
           - attributeType
         type: object
         properties:
           attributeID:
             type: integer
             format: int32
             example: 1
           attributeType:
             type: integer
             format: int32
             example: 32
         xml:
           name: ZigbeeAttribute

   ## Attributes that define a Zigbee attribute
       ZigbeeAttributes:
         required:
           - zigbee
         type: object
         properties:
           zigbee:
             required:
               - endpointID
               - clusterID
               - attributeID
             type: object
             properties:
               endpointID:
                 type: integer
                 format: int32
                 example: 1
               clusterID:
                 type: integer
                 format: int32
                 example: 6
               attributeID:

Brinckman, et al.        Expires 23 October 2024               [Page 92]
Internet-Draft                    NIPC                        April 2024

                 type: integer
                 format: int32
                 example: 16
               type:
                 type: integer
                 format: int32
                 example: 1
         xml:
           name: ZigbeeAttributes

   ## Attributes that define a Zigbee broadcast
       ZigbeeBroadcast:
         required:
           - zigbee
         type: object
         properties:
           zigbee:
             required:
               - endpointID
               - clusterID
               - attributeID
               - value
             type: object
             properties:
               endpointID:
                 type: integer
                 format: int32
                 example: 1
               clusterID:
                 type: integer
                 format: int32
                 example: 6
               attributeID:
                 type: integer
                 format: int32
                 example: 16
               type:
                 type: integer
                 format: int32
                 example: 1
               value:
                 type: integer
                 format: int32
                 example: 15
         xml:
           name: ZigbeeBroadcast

   # Common objects

Brinckman, et al.        Expires 23 October 2024               [Page 93]
Internet-Draft                    NIPC                        April 2024

   ## A SCIM object, can be a  device or a group
       Object:
         required:
           - id
         type: object
         properties:
           id:
             type: string
             format: uuid
             example: 12345678-1234-5678-1234-56789abcdef4
           type:
             type: string
             example: device
             enum:
               - device
               - group
           technology:
             type: string
             example: ble
             enum:
               - ble
               - zigbee
         xml:
           name: Object

   ## A Service is a device with optional service IDs
       Service:
         allOf:
           - $ref: '#/components/schemas/Object'
         type: object
         properties:
           ble:
             type: object
             properties:
               services:
                 type: array
                 xml:
                   name: services
                   wrapped: true
                 items:
                   $ref: '#/components/schemas/BLEServiceID'
               cached:
                 description: |-
                   If we can cache information, then device doesn't need
                   to be rediscovered before every connected.
                 type: boolean
                 default: false
               cacheIdlePurge:

Brinckman, et al.        Expires 23 October 2024               [Page 94]
Internet-Draft                    NIPC                        April 2024

                 description: cache expiry period, when device allows
                 type: integer
                 example: 3600 # default 1 hour
               autoUpdate:
                 description: |-
                   autoupdate services if device supports it (default)
                 type: boolean
                 example: true
             xml:
               name: ble
         xml:
           name: Service

   ## A Connection
       Connection:
         allOf:
           - $ref: '#/components/schemas/Service'
         type: object
         properties:
           retries:
             type: integer
             format: int32
             example: 3
           retryMultipleAPs:
             type: boolean
             example: true
         xml:
           name: Connection

   ## A specific attribute of an Device
       Attribute:
         allOf:
           - $ref: '#/components/schemas/Object'
         oneOf:
           - $ref: '#/components/schemas/BLEAttributes'
           - $ref: '#/components/schemas/ZigbeeAttributes'
         discriminator:
           propertyName: technology
           mapping:
             ble: '#/components/schemas/BLEAttributes'
             zigbee: '#/components/schemas/ZigbeeAttributes'
         xml:
           name: Attribute

   ## A value of an attribute of an Device
       AttributeValue:
         allOf:
           - $ref: '#/components/schemas/Attribute'

Brinckman, et al.        Expires 23 October 2024               [Page 95]
Internet-Draft                    NIPC                        April 2024

         required:
           - value
         type: object
         properties:
           value:
             type: string
             format: byte
             example: 0001
           forcedResponse:
             description: do or do not wait for a response?
             type: boolean
             example: true
         xml:
           name: AttributeValue

   ## A file-based attribute of an Device
       AttributeFile:
         allOf:
           - $ref: '#/components/schemas/Attribute'
         required:
           - filename
         type: object
         properties:
           filename:
             type: string
             example: "firmware.dat"
           chunksize:
             type: integer
           forcedResponse:
             description: do or do not wait for a response?
             type: boolean
             example: true
         xml:
           name: AttributeFile

   ## A binary blob-based attribute of an Device
       AttributeBlob:
         allOf:
           - $ref: '#/components/schemas/Attribute'
         required:
           - blob
         type: object
         properties:
           blob:
             type: string
             format: binary
           chunksize:
             type: integer

Brinckman, et al.        Expires 23 October 2024               [Page 96]
Internet-Draft                    NIPC                        April 2024

           forcedResponse:
             description: do or do not wait for a response?
             type: boolean
             example: true
         xml:
           name: AttributeFile

   ## Conditional read of a value (read until specific value is read)
       AttributeConditional:
         allOf:
           - $ref: '#/components/schemas/Attribute'
         required:
           - value
         type: object
         properties:
           value:
             type: string
             format: byte
             example: 0001
           maxTime:
             description: |-
               maximum time the conditional read should run in seconds
               (default 10 sec, max 60 sec)
             type: integer
           maxRepeat:
             description: |-
              maximum time the conditional read should repeat
              (default 5, max 60)
             type: integer
           frequency:
             description: |-
               time between reads in seconds (default 1, max 60)
             type: integer
         xml:
           name: AttributeConditional

   ## A subscription attribute of an Device
       Subscription:
         allOf:
           - $ref: '#/components/schemas/Attribute'
         type: object
         properties:
           topic:
             type: string
             example: enterprise/hospital/pulse_oximeter
           dataFormat:
             description: |-
               how is information decorated? default: timestamped and

Brinckman, et al.        Expires 23 October 2024               [Page 97]
Internet-Draft                    NIPC                        April 2024

               attribute ids.
             type: string
             example: default
             enum:
               - default # decorated with attribute ids
               - timestamped
               - payload
           replay:
             type: boolean
             example: false
             default: false
           forcedAck:
             description: |-
               When not looking at device/attribute support MUST we
               ackhnowledge?
             type: boolean
             example: true
         xml:
           name: Subscription

   ## A broadcast
       Broadcast:
         allOf:
           - $ref: '#/components/schemas/Object'
         oneOf:
           - $ref: '#/components/schemas/BLEBroadcast'
           - $ref: '#/components/schemas/ZigbeeBroadcast'
         discriminator:
           propertyName: technology
           mapping:
             ble: '#/components/schemas/BLEBroadcast'
             zigbee: '#/components/schemas/ZigbeeBroadcast'
         required:
           - cycle
         type: object
         properties:
           cycle:
             type: string
             example: single
             enum:
               - single
               - repeat
           # broadcast time in ms
           broadcastTime:
             type: integer
             example: 3000
           # interval between broadcasts in ms
           broadcastInterval:

Brinckman, et al.        Expires 23 October 2024               [Page 98]
Internet-Draft                    NIPC                        April 2024

             type: integer
             example: 500
         xml:
           name: Broadcast

   ## Topic Name
       TopicName:
         required:
           - topic
         type: object
         properties:
           topic:
             type: string
             example: enterprise/hospital/pulse_oximeter
         xml:
           name: TopicName

   ## DataStream Topic
       Topic:
         allOf:
           - $ref: '#/components/schemas/TopicName'
         oneOf:
           - $ref: '#/components/schemas/BLETopic'
           - $ref: '#/components/schemas/ZigbeeAttributes'
         discriminator:
           propertyName: technology
           mapping:
             ble: '#/components/schemas/BLETopic'
             zigbee: '#/components/schemas/ZigbeeAttributes'
         type: object
         properties:
           dataFormat:
             description: |-
               How is information decorated?  Default: device
               and attribute ids.
             type: string
             example: default
             enum:
               - default
               - timestamped
               - payload
           replay:
             type: string
             example: off
             enum:
               - off #default
               - on
           dataApps:

Brinckman, et al.        Expires 23 October 2024               [Page 99]
Internet-Draft                    NIPC                        April 2024

             type: array
             xml:
               name: dataApps
               wrapped: true
             items:
               type: object
               properties:
                 dataAppID:
                   type: string
                   example: https://data-app-1
         xml:
           name: Topic

   ## FileName
       FileName:
         required:
           - filename
         type: object
         properties:
           filename:
             type: string
             example: "firmware.dat"
         xml:
           name: FileName

   ## File
       File:
         allOf:
           - $ref: '#/components/schemas/FileName'
         type: object
         properties:
           file: #file itself is provided
             type: string
             format: binary
           fileURL: #file can be downloaded from a URL
             type: string
             example: "https://domain.com/firmware.dat"
         xml:
           name: File

   ## Defines an operation in a bulk API
       Operation:
         required:
           - operation
         allOf:
           - type: object
             properties:
               operation:

Brinckman, et al.        Expires 23 October 2024              [Page 100]
Internet-Draft                    NIPC                        April 2024

                 type: string
                 enum:
                  - /extension/connection/create
                  - /extension/connection/delete
                  - /extension/attribute/read
                  - /extension/attribute/write
                  - /extension/attribute/write/file
                  - /extension/attribute/write/blob
                  - /extension/attribute/read/conditional
           - oneOf:
               - $ref: '#/components/schemas/Service'
               - $ref: '#/components/schemas/Attribute'
               - $ref: '#/components/schemas/AttributeValue'
               - $ref: '#/components/schemas/AttributeConditional'
               - $ref: '#/components/schemas/AttributeFile'
               - $ref: '#/components/schemas/AttributeBlob'
             discriminator:
               propertyName: operation
               mapping:
                 /extension/connection/create:
                   '#/components/schemas/Service'
                 /extension/attribute/read:
                   '#/components/schemas/Attribute'
                 /extension/attribute/read/conditional:
                   '#/components/schemas/AttributeConditional'
                 /extension/attribute/write:
                   '#/components/schemas/AttributeValue'
                 /extension/attribute/write/file:
                   '#/components/schemas/AttributeFile'
                 /extension/attribute/write/blob:
                   '#/components/schemas/AttributeBlob'
         xml:
           name: Operation

   ## Bulk schema
       Bulk:
         allOf:
           - $ref: '#/components/schemas/Object'
         type: object
         properties:
           autoDisconnect:
             description: |-
               do we automatically disconnect after a RESTful operation?
             type: boolean
             example: true
             default: true
           operations:
             type: array

Brinckman, et al.        Expires 23 October 2024              [Page 101]
Internet-Draft                    NIPC                        April 2024

             xml:
               name: operations
               wrapped: true
             items:
               $ref: '#/components/schemas/Operation'
         xml:
           name: Bulk

   # responses
   ## Baseline success reponse
       Success:
         required:
           - status
         type: object
         properties:
           status:
             type: string
             example: SUCCESS
             enum:
               - SUCCESS
           requestID:
             type: string
             example: 12345678-5678-1234-5578-abcdef1234

       SuccessResponse:
         allOf:
           - $ref: '#/components/schemas/Success'
         type: object
         properties:
           id:
             type: string
             format: uuid
             example: 12345678-1234-5678-1234-56789abcdef4

   ## Error 500 application Failure response
       FailureResponse:
         required:
           - status
           - errorCode
         type: object
         properties:
           status:
             type: string
             example: FAILURE
             enum:
               - FAILURE
           reason:
             type: string

Brinckman, et al.        Expires 23 October 2024              [Page 102]
Internet-Draft                    NIPC                        April 2024

             example: Not Found
           errorCode:
             type: integer
             format: int32
             example: 12
           requestID:
             type: string
             example: 12345678-5678-1234-5578-abcdef1234

   ## Response, success or failure
       Response:
         oneOf:
           - $ref: '#/components/schemas/SuccessResponse'
           - $ref: '#/components/schemas/FailureResponse'
         xml:
           name: Response

   ## Success response for binding API
       BindingResponse:
         oneOf:
           - $ref: '#/components/schemas/SuccessResponse'
           - $ref: '#/components/schemas/ZigbeeBindingResponse'
           - $ref: '#/components/schemas/FailureResponse'
         xml:
           name: BindingeResponse

   ## Returning multiple bindings
       MultiBindingsResponse:
         allOf:
           - $ref: '#/components/schemas/Success'
         required:
           - bindings
         type: object
         properties:
           bindings:
             type: array
             xml:
               name: bindings
               wrapped: true
             items:
               $ref: '#/components/schemas/BindingResponse'
         xml:
           name: MultiBindingsResponse

   ## Returns Zigbee node & pan ID
       ZigbeeBindingResponse:
         allOf:
           - $ref: '#/components/schemas/SuccessResponse'

Brinckman, et al.        Expires 23 October 2024              [Page 103]
Internet-Draft                    NIPC                        April 2024

         type: object
         properties:
           nodeID:
             type: integer
             format: int32
             example: 65234
           panID:
             type: integer
             format: int32
             example: 48734
         xml:
           name: ZigbeeBindgingResponse

    ## Returns discovered services
       ServiceResponse:
         allOf:
           - $ref: '#/components/schemas/SuccessResponse'
         oneOf:
           - $ref: '#/components/schemas/BLEServiceslist'
           - $ref: '#/components/schemas/ZigbeeEndpointlist'
         xml:
           name: ConnectionResponse

   ## Response to multiple connections
       MultiConnectionsResponse:
         allOf:
           - $ref: '#/components/schemas/Success'
         required:
           - connections
         type: object
         properties:
           connections:
             type: array
             xml:
               name: connections
               wrapped: true
             items:
               $ref: '#/components/schemas/Response'
         xml:
           name: MultiConnectionsResponse

   ## Returns an attribute value
       AttributeValueResponse:
         allOf:
           - $ref: '#/components/schemas/SuccessResponse'
         required:
          - value
         type: object

Brinckman, et al.        Expires 23 October 2024              [Page 104]
Internet-Draft                    NIPC                        April 2024

         properties:
           value:
             type: string
             example: 01
             format: byte
         xml:
           name: AttributeValueResponse

   ## Returns a topic
       TopicResponse:
         allOf:
           - $ref: '#/components/schemas/SuccessResponse'
         required:
           - topic
         type: object
         properties:
           topic:
             type: string
             example: enterprise/hospital/pulse_oximeter
         xml:
           name: TopicResponse

   ## Returning multiple topics
       MultiTopicsResponse:
         allOf:
           - $ref: '#/components/schemas/Success'
         required:
           - topics
         type: object
         properties:
           topics:
             type: array
             xml:
               name: topics
               wrapped: true
             items:
               $ref: '#/components/schemas/TopicName'
         xml:
           name: MultiTopicsResponse

   ## Returning multiple subscriptions
       MultiSubscriptionResponse:
         allOf:
           - $ref: '#/components/schemas/Success'
         required:
           - subscriptions
         type: object
         properties:

Brinckman, et al.        Expires 23 October 2024              [Page 105]
Internet-Draft                    NIPC                        April 2024

           subscriptions:
             type: array
             xml:
               name: subscriptions
               wrapped: true
             items:
               $ref: '#/components/schemas/Subscription'
         xml:
           name: MultiSubscriptionResponse

   ## Returns a file name
       FileResponse:
         allOf:
           - $ref: '#/components/schemas/SuccessResponse'
         required:
           - filename
         type: object
         properties:
           filename:
             type: string
             example: "firmware.dat"
         xml:
           name: FileResponse

   ## Returning multiple file names
       MultiFileResponse:
         allOf:
           - $ref: '#/components/schemas/Success'
         required:
           - filenames
         type: object
         properties:
           filenames:
             type: array
             xml:
               name: filenames
               wrapped: true
             items:
               $ref: '#/components/schemas/FileName'
         xml:
           name: MultiFileResponse

   ## Multiple returns for a bulk operation
       BulkResponse:
         allOf:
           - $ref: '#/components/schemas/SuccessResponse'
         type: object
         properties:

Brinckman, et al.        Expires 23 October 2024              [Page 106]
Internet-Draft                    NIPC                        April 2024

           operations:
             type: array
             xml:
               name: operations
               wrapped: true
             items:
               $ref: '#/components/schemas/OperationResponse'
         xml:
           name: BulkResponse

   ## Return for an operation
       OperationResponse:
         required:
           - operation
         allOf:
           - type: object
             properties:
               operation:
                 type: string
                 enum:
                  - /connectivity/connection/create
                  - /connectivity/connection/delete
                  - /extension/attribute/read
                  - /extension/attribute/write
                  - /extension/attribute/write/file
                  - /extension/attribute/write/blob
                  - /extension/attribute/read/conditional
           - oneOf:
             - $ref: '#/components/schemas/ServiceResponse'
             - $ref: '#/components/schemas/SuccessResponse'
             - $ref: '#/components/schemas/AttributeValueResponse'
             discriminator:
               propertyName: operation
               mapping:
                 /connectivity/connection/create:
                   '#/components/schemas/ServiceResponse'
                 /connectivity/connection/delete:
                   '#/components/schemas/SuccessResponse'
                 /extension/attribute/read:
                   '#/components/schemas/AttributeValueResponse'
                 /extension/attribute/write:
                   '#/components/schemas/AttributeValueResponse'
                 /extension/attribute/write/file:
                   '#/components/schemas/SuccessResponse'
                 /extension/attribute/write/blob:
                   '#/components/schemas/SuccessResponse'
                 /extension/attribute/read/conditional:
                   '#/components/schemas/AttributeValueResponse'

Brinckman, et al.        Expires 23 October 2024              [Page 107]
Internet-Draft                    NIPC                        April 2024

         xml:
           name: Operation

    # API key authorization
     securitySchemes:
       ApiKeyAuth:
         type: apiKey
         in: header
         name: X-API-KEY
   # Apply the API key globally to all operations
   security:
     - ApiKeyAuth: []
   <CODE ENDS>

                                  Figure 6

Appendix B.  Protobuf definition

   The following non-normative protocol buffer definition is provide for
   convenience of the implementor.

   <CODE BEGINS> file "data_app.proto"
   syntax = "proto3";

   option java_package = "org.ietf.nipc.proto";
   option java_multiple_files = true;

   package nipc;

   message DataSubscription {
       optional string device_id = 1;
       bytes data = 2;

       oneof subscription {
           BLESubscription ble_subscription = 3;
           BLEAdvertisement ble_advertisement = 4;
           ZigbeeSubscription zigbee_subscription = 5;
           RawPayload raw_payload = 6;
           BLEConnectionStatus ble_connection_status = 7;
       }

       message BLESubscription {
           optional string service_uuid = 1;
           optional string characteristic_uuid = 2;
       }

       message BLEAdvertisement {
           string mac_address = 1;

Brinckman, et al.        Expires 23 October 2024              [Page 108]
Internet-Draft                    NIPC                        April 2024

           optional int32 rssi = 2;
       }

       message ZigbeeSubscription {
           optional int32 endpoint_id = 1;
           optional int32 cluster_id = 2;
           optional int32 attribute_id = 3;
           optional int32 attribute_type = 4;
       }

       message BLEConnectionStatus {
           string mac_address = 1;
           bool connected = 2;
           optional int32 reason = 3;
       }

       message RawPayload {
           optional string context_id = 1;
       }
   }
   <CODE ENDS>

                                  Figure 7

Authors' Addresses

   Bart Brinckman
   Cisco Systems
   Brussels
   Belgium
   Email: bbrinckm@cisco.com

   Rohit Mohan
   Cisco Systems
   170 West Tasman Drive
   San Jose,  95134
   United States of America
   Email: rohitmo@cisco.com

   Braeden Sanford
   Philips
   Cambridge,
   United States of America
   Email: braeden.sanford@philips.com

Brinckman, et al.        Expires 23 October 2024              [Page 109]