From 1c804a5159f67370f005dbf0cc82e5c7e72725f0 Mon Sep 17 00:00:00 2001 From: Christopher Aubut <89488056+caubut-charter@users.noreply.github.com> Date: Mon, 8 Jul 2024 20:14:25 +0000 Subject: [PATCH] chore: adds initial proposal from the backlog working group (#7) * chore: adds initial proposal from the backlog working group Co-authored-by: Herbert Damker <52109189+hdamker@users.noreply.github.com> Co-authored-by: Ben Hepworth <125334035+benhepworth@users.noreply.github.com> --- code/API_definitions/README.MD | 1 - .../network_access_management.yaml | 3060 +++++++++++++++++ 2 files changed, 3060 insertions(+), 1 deletion(-) delete mode 100644 code/API_definitions/README.MD create mode 100644 code/API_definitions/network_access_management.yaml diff --git a/code/API_definitions/README.MD b/code/API_definitions/README.MD deleted file mode 100644 index 04313f1..0000000 --- a/code/API_definitions/README.MD +++ /dev/null @@ -1 +0,0 @@ -Here you can add your definitions and delete this README.MD file diff --git a/code/API_definitions/network_access_management.yaml b/code/API_definitions/network_access_management.yaml new file mode 100644 index 0000000..d45ad66 --- /dev/null +++ b/code/API_definitions/network_access_management.yaml @@ -0,0 +1,3060 @@ +openapi: 3.0.3 + +info: + title: Home Devices - Network Access Management + description: | + Service enabling API for managing network operator supplied network access devices. This APIs initial focus is on + managing **Isolated Networks** and device reboot requests. + + # Introduction + An isolated network is a network access configuration where each configuration is for a logically separated Local + Area Network (LAN). Application developers can create, modify, or remove these networks which could be useful in + scenarios such as: + + - A property owner wants to create a temporary network for the duration of a short-term booking or long-term rental. + - A property manager wants to replicate the network access details across multiple network access devices at one or + more locations such as common areas, offices, etc. + - A security/privacy-minded user wants to create one or more networks for their guests or Internet-of-Thing (IoT) + network clients. + + A reboot request is simply a request to reboot a network operator supplied network access device. Application + developers can create these requests which could be useful in scenarios such as: + + - A property owner wants to recover from a faulty network state by rebooting a gateway device. + - A property manager wants to reboot multiple devices at one or more locations such as common areas, offices, etc. + + # Relevant Terms and Definitions + - **Isolated Network**: Network access configuration where each configuration is for a logically separated Local + Area Network (LAN) when on the same network access device. Isolation in this context means that traffic will not be + forwarded or routed from one logical LAN to another on the same device. The isolation implementation must be + considered a logical construct only. Network operators are free to choose how to implement this behavior using any + number of technologies such as with VLANs or OpenFlow rules. Traffic between two network clients using the same + isolated network access details, but across different network access devices, is currently undefined behavior. + - **Reboot Request**: A request to reboot a network operator supplied network access device. + - **Device**: A network operator supplied network access device that supports isolated networks. Multiple devices + that support LAN connectivity across the same isolated network (e.g., mesh Wi-Fi, Thread personal area network, + etc.) SHOULD be presented as a single device for implementations of this API. + - **Network Operator**: Service provider that implements this API and has operational control of supporting devices. + - **Service Owner**: Customer of a network operator and resource owner with one or more devices that supports this + API across one or more service sites. + - **Service Site**: A distinct service owner location, as interpreted by the network operator, with one or more + devices. A service site typically has a one-to-one relationship with the mailing address of the location. Network + operators that support a single identity or interchangeable identities for multiple service sites at the same + mailing address (e.g., a residential and business account, an office and common area account, etc.) MUST provide + some distinction in the property address (e.g., attn: Home Office, attn: Common Area, etc.). Multiple service + sites, for the same mailing address, but for unrelated service owner identities, do not have this requirement. + - **End-User**: The user connecting to an isolated network with a network client. + - **Network Client**: End-user equipment connecting to an isolated network (e.g., laptop, phone, IoT device, etc.). + - **API Client**: A first- or third-party software system using this API. + + # API Functionality + This API allows API clients to manage isolated networks and reboot network access devices. + + ## Authorization and authentication + + [Camara Security and Interoperability Profile](https://github.com/camaraproject/IdentityAndConsentManagement/blob/main/documentation/CAMARA-Security-Interoperability.md) + provides details on how a client requests an access token. + + Which specific authorization flows are to be used will be determined during onboarding process, happening between + the API Client and the Telco Operator exposing the API, taking into account the declared purpose for accessing the + API, while also being subject to the prevailing legal framework dictated by local legislation. + + It is important to remark that in cases where personal user data is processed by the API, and users can exercise + their rights through mechanisms such as opt-in and/or opt-out, the use of 3-legged access tokens becomes mandatory. + This measure ensures that the API remains in strict compliance with user privacy preferences and regulatory + obligations, upholding the principles of transparency and user-centric data control. + + ### Scopes + Scopes are used to protect the service owner's information and privacy. The general format is + `--`. A resource may be further broken down into `-` or + `-` for granular permissions. Scopes also control output information as opposed to just + authorizing endpoints. Each endpoint definition will clearly state what scopes are needed for access and which are + needed to access additional information. Below are some general rules for scopes in this API. + + - Regulated information, such as physical locations or hardware addresses of network devices, have special scopes. + Network operators are expected to follow any local regulations when sharing this information with an API client. + - Scopes have inheritance when one scope would otherwise require the inherited scope. + - Read scopes for one resource impacts the output of another resource when the requested resource has a relationship + with the first (e.g., listing networks on a device requires both device and network read scopes). + - Isolated networks are broken down into 3 roles allowing service owners to grant granular permissions to API + clients: only-own, primary, and auxiliary. The primary role allows API clients to manage the main network access + configuration. The auxiliary role allows API clients to manage all auxiliary (i.e., secondary) networks. The + only-own role allows API clients to manage networks it has created. Only-own networks SHOULD be an auxiliary, or + secondary, network. Note that there is an edge case when a service owner revokes the primary role authorization. An + API client SHOULD be able to continue managing primary isolated networks created by the client. Complete + administrative control requires both the primary and auxiliary roles. + + | Scope | Description | Inherits + |-------|-------------|--------- + | **network-access-management:service-sites:read** | List a service owner's service sites + | **network-access-management:service-sites.location:read** | Read a service site's physical location | network-access-management:service-sites:read + | **network-access-management:devices:read** | List a service owner's devices + | **network-access-management:devices.hardware-address:read** | Read a service owner's device's hardware address | network-access-management:devices:read + | **network-access-management:devices:write** | Modify which networks are configured on a service owner's devices | network-access-management:devices:read + | **network-access-management:isolated-networks:read** | List a service owner's isolated networks created by the calling API client + | **network-access-management:isolated-networks:write** | Create or modify a service owner's isolated networks created by the calling API client | network-access-management:isolated-networks:read + | **network-access-management:isolated-networks.primary:read** | Access information about a service owner's primary isolated network + | **network-access-management:isolated-networks.primary:write** | Modify a service owner's primary isolated network | network-access-management:isolated-networks.primary:read + | **network-access-management:isolated-networks.auxiliary:read** | List a service owner's auxiliary isolated networks | network-access-management:isolated-networks:read + | **network-access-management:isolated-networks.auxiliary:write** | Create or modify a service owner's auxiliary isolated networks | network-access-management:isolated-networks.auxiliary:read
network-access-management:isolated-networks:write + | **network-access-management:reboot-requests:read** | List a service owner's reboot requests created by the calling API client + | **network-access-management:reboot-requests:write** | Create or modify a service owner's reboot request created by the calling API client | network-access-management:reboot-request:read + + ## General Usage + This API is intended for creating, modifying, or deleting isolated networks using the `/isolated-networks` endpoints + to build access detail configurations. The `/service-sites` endpoints are used for iterating over a service owner's + locations. The exact location may be requested with an additional scope to assist with reconciling information about + service sites when the API client operator has an existing relationship with the service owner. Similarly, the + `/devices` endpoints are used for iterating over and configuring a service owner's devices. The hardware address + may be requested for the same purpose of reconciling information from another source (e.g., database, persons with + physical device access, etc.). + + ## Optional Modes + + ### Default Device + When an identity for access token has a "default device", such as a typical residential customer with one service + site and one network access device, service site and device scopes MAY be omitted. Any fields referencing a + network access device using the `/isolated-networks` or `/isolated-networks/*` APIs MUST be left blank by API + clients. Network operators SHOULD substitute the missing field with the default device. API definitions include + additional details for error responses so API clients can detect if this mode is available. + + ## Comments for Network Operators + The following comments are for Network Operators implementing this API. + + ### Auto-Deleting Isolated Networks + When an isolated network is not configured on any device the network configuration and its identifier SHOULD be + auto-deleted. API clients MUST not be expected to delete networks not configured on any device. + + ### Mesh Systems + Mesh systems SHOULD be represented as a single device when implementing this API due to the undefined behavior of + LAN connectivity across multiple devices with the same isolated network. The recommendation is to use the gateway + hardware address of the mesh system when exposing that field, though the hardware address of any node in the mesh + may be used. If an end-user replaces the equipment, all existing isolated networks SHOULD be synced to the new + device representing this mesh. Alternatively, a synthetic hardware address may also be used if the specification + for the address type allows. + version: wip + license: + name: Apache 2.0 + url: https://www.apache.org/licenses/LICENSE-2.0.html + x-camara-commonalities: 0.4.0 + contact: + email: sp-nam@lists.camaraproject.org + +servers: + - url: "{apiRoot}/network-access-management/v0" + variables: + apiRoot: + default: http://localhost:9091 + description: API root, defined by the service provider, e.g. `api.example.com` or `api.example.com/somepath` + +tags: + - name: Retrieve Service Site + description: Operations to retrieve information about service sites + - name: Retrieve Device + description: Operations to retrieve information about devices + - name: Apply Device Network Configuration + description: Operations to apply isolated network configurations to devices + - name: Retrieve Isolated Network + description: Operations to retrieve information about isolated networks + - name: Configure and Apply Isolated Network + description: Operations to modify isolated networks and apply to devices + - name: Retrieve Reboot Request + description: Operations to retrieve information about reboot requests + - name: Configure Reboot Requests + description: Operations to modify reboot requests + +paths: + /service-sites: + get: + tags: + - Retrieve Service Site + summary: Get all service sites + security: + - openId: + - network-access-management:service-sites:read + operationId: getServiceSites + description: | + Returns all service sites. Scopes impact the output of this endpoint. See the examples for various + permutations. + + **Required Scopes:** + - **one of** + - `network-access-management:service-sites:read` + - `network-access-management:service-sites.location:read` + + **Optional Scopes:** + - `network-access-management:devices:read` + - `network-access-management:devices:write` + - `network-access-management:devices.hardware-address:read` + responses: + "200": + description: Contains information about all service sites + content: + application/json: + schema: + $ref: "#/components/schemas/ServiceSiteList" + examples: + BaseServiceSiteList: + $ref: "#/components/examples/BaseServiceSiteList" + ServiceSiteListWithLocation: + $ref: "#/components/examples/ServiceSiteListWithLocation" + ServiceSiteListWithDevices: + $ref: "#/components/examples/ServiceSiteListWithDevices" + ServiceSiteListWithLocationAndDevices: + $ref: "#/components/examples/ServiceSiteListWithLocationAndDevices" + "401": + $ref: "#/components/responses/Generic401" + "403": + $ref: "#/components/responses/Generic403" + "500": + $ref: "#/components/responses/Generic500" + "501": + $ref: "#/components/responses/Generic501" + "503": + $ref: "#/components/responses/Generic503" + + /service-sites/{siteId}: + get: + tags: + - Retrieve Service Site + summary: Get a service site by ID + security: + - openId: + - network-access-management:service-sites:read + operationId: getServiceSite + description: | + Returns a service site that matches the given ID. Scopes impact the output of this endpoint. See the examples + for various permutations. + + **Required Scopes:** + - **one of** + - `network-access-management:service-sites:read` + - `network-access-management:service-sites.location:read` + + **Optional Scopes:** + - `network-access-management:devices:read` + - `network-access-management:devices:write` + - `network-access-management:devices.hardware-address:read` + parameters: + - $ref: "#/components/parameters/siteId" + responses: + "200": + description: Contains information about the service site + content: + application/json: + schema: + $ref: "#/components/schemas/ServiceSite" + examples: + BaseServiceSite: + $ref: "#/components/examples/BaseServiceSite" + ServiceSiteWithLocation: + $ref: "#/components/examples/ServiceSiteWithLocation" + ServiceSiteWithDevices: + $ref: "#/components/examples/ServiceSiteWithDevices" + ServiceSiteWithLocationAndDevices: + $ref: "#/components/examples/ServiceSiteWithLocationAndDevices" + "400": + $ref: "#/components/responses/Generic400" + "401": + $ref: "#/components/responses/Generic401" + "403": + $ref: "#/components/responses/Generic403" + "404": + $ref: "#/components/responses/ServiceSiteNotFound404" + "500": + $ref: "#/components/responses/Generic500" + "501": + $ref: "#/components/responses/Generic501" + "503": + $ref: "#/components/responses/Generic503" + + /service-sites/{siteId}/devices: + get: + tags: + - Retrieve Device + summary: Get all devices at a service site + security: + - openId: + - network-access-management:service-sites:read + - network-access-management:devices:read + operationId: getDevicesByServiceSite + description: | + Returns all devices at a service site that matches the given ID. Scopes impact the output of this endpoint. + See the examples for various permutations. + + **Required Scopes:** + - **all of** + - **one of** + - `network-access-management:service-sites:read` + - `network-access-management:service-sites.location:read` + - **one of** + - `network-access-management:devices:read` + - `network-access-management:devices:write` + - `network-access-management:devices.hardware-address:read` + + **Optional Scopes:** + - `network-access-management:isolated-networks:read` + - `network-access-management:isolated-networks:write` + - `network-access-management:isolated-networks.primary:read` + - `network-access-management:isolated-networks.primary:write` + - `network-access-management:isolated-networks.auxiliary:read` + - `network-access-management:isolated-networks.auxiliary:write` + parameters: + - $ref: "#/components/parameters/siteId" + responses: + "200": + description: Contains information about devices at the service site + content: + application/json: + schema: + $ref: "#/components/schemas/DeviceList" + examples: + DeviceListWithServiceSite: + $ref: "#/components/examples/DeviceListWithServiceSite" + DeviceListWithHardwareAddressAndServiceSite: + $ref: "#/components/examples/DeviceListWithHardwareAddressAndServiceSite" + DeviceListWithServiceSiteAndNetworks: + $ref: "#/components/examples/DeviceListWithServiceSiteAndNetworks" + DeviceListWithHardwareAddressAndServiceSiteAndNetworks: + $ref: "#/components/examples/DeviceListWithHardwareAddressAndServiceSiteAndNetworks" + "400": + $ref: "#/components/responses/Generic400" + "401": + $ref: "#/components/responses/Generic401" + "403": + $ref: "#/components/responses/Generic403" + "404": + $ref: "#/components/responses/ServiceSiteNotFound404" + "500": + $ref: "#/components/responses/Generic500" + "501": + $ref: "#/components/responses/Generic501" + "503": + $ref: "#/components/responses/Generic503" + + /service-sites/{siteId}/isolated-networks: + get: + tags: + - Retrieve Service Site + summary: Get all networks at a service site + security: + - openId: + - network-access-management:service-sites:read + - network-access-management:devices:read + - network-access-management:isolated-networks:read + operationId: getNetworksByServiceSite + description: | + Returns all networks at a service site that matches the given ID. + + **Required Scopes:** + - **all of** + - **one of** + - `network-access-management:service-sites:read` + - `network-access-management:service-sites.location:read` + - **one of** + - `network-access-management:devices:read` + - `network-access-management:devices:write` + - `network-access-management:devices.hardware-address:read` + - **one of** + - `network-access-management:isolated-networks:read` + - `network-access-management:isolated-networks:write` + - `network-access-management:isolated-networks.primary:read` + - `network-access-management:isolated-networks.primary:write` + - `network-access-management:isolated-networks.auxiliary:read` + - `network-access-management:isolated-networks.auxiliary:write` + parameters: + - $ref: "#/components/parameters/siteId" + responses: + "200": + description: Contains information about networks at the service site + content: + application/json: + schema: + $ref: "#/components/schemas/NetworkList" + examples: + NetworkListWithDevices: + $ref: "#/components/examples/NetworkListWithDevices" + "400": + $ref: "#/components/responses/Generic400" + "401": + $ref: "#/components/responses/Generic401" + "403": + $ref: "#/components/responses/Generic403" + "404": + $ref: "#/components/responses/ServiceSiteNotFound404" + "500": + $ref: "#/components/responses/Generic500" + "501": + $ref: "#/components/responses/Generic501" + "503": + $ref: "#/components/responses/Generic503" + + /devices: + get: + tags: + - Retrieve Device + summary: Get all devices + security: + - openId: + - network-access-management:devices:read + operationId: getDevices + description: | + Returns all devices. Scopes impact the output of this endpoint. See the examples for various permutations. + + **Required Scopes:** + - **one of** + - `network-access-management:devices:read` + - `network-access-management:devices:write` + - `network-access-management:devices.hardware-address:read` + + **Optional Scopes:** + - **one of** + - `network-access-management:service-sites:read` + - `network-access-management:service-sites.location:read` + - `network-access-management:isolated-networks:read` + - `network-access-management:isolated-networks:write` + - `network-access-management:isolated-networks.primary:read` + - `network-access-management:isolated-networks.primary:write` + - `network-access-management:isolated-networks.auxiliary:read` + - `network-access-management:isolated-networks.auxiliary:write` + responses: + "200": + description: Contains information about all devices + content: + application/json: + schema: + $ref: "#/components/schemas/DeviceList" + examples: + BaseDeviceList: + $ref: "#/components/examples/BaseDeviceList" + DeviceListWithHardwareAddress: + $ref: "#/components/examples/DeviceListWithHardwareAddress" + DeviceListWithServiceSite: + $ref: "#/components/examples/DeviceListWithServiceSite" + DeviceListWithNetworks: + $ref: "#/components/examples/DeviceListWithNetworks" + DeviceListWithHardwareAddressAndServiceSite: + $ref: "#/components/examples/DeviceListWithHardwareAddressAndServiceSite" + DeviceListWithHardwareAddressAndNetworks: + $ref: "#/components/examples/DeviceListWithHardwareAddressAndNetworks" + DeviceListWithServiceSiteAndNetworks: + $ref: "#/components/examples/DeviceListWithServiceSiteAndNetworks" + DeviceListWithHardwareAddressAndServiceSiteAndNetworks: + $ref: "#/components/examples/DeviceListWithHardwareAddressAndServiceSiteAndNetworks" + "401": + $ref: "#/components/responses/Generic401" + "403": + $ref: "#/components/responses/Generic403" + "500": + $ref: "#/components/responses/Generic500" + "501": + $ref: "#/components/responses/Generic501" + "503": + $ref: "#/components/responses/Generic503" + + /devices/{deviceId}: + get: + tags: + - Retrieve Device + summary: Get a device by ID + security: + - openId: + - network-access-management:devices:read + operationId: getDevice + description: | + Returns a device that matches the given ID. Scopes impact the output of this endpoint. See the examples for + various permutations. + + **Required Scopes:** + - **one of** + - `network-access-management:devices:read` + - `network-access-management:devices:write` + - `network-access-management:devices.hardware-address:read` + + **Optional Scopes:** + - **one of** + - `network-access-management:service-sites:read` + - `network-access-management:service-sites.location:read` + - `network-access-management:isolated-networks:read` + - `network-access-management:isolated-networks:write` + - `network-access-management:isolated-networks.primary:read` + - `network-access-management:isolated-networks.primary:write` + - `network-access-management:isolated-networks.auxiliary:read` + - `network-access-management:isolated-networks.auxiliary:write` + parameters: + - $ref: "#/components/parameters/deviceId" + responses: + "200": + description: Contains information about the device + content: + application/json: + schema: + $ref: "#/components/schemas/Device" + examples: + BaseDevice: + $ref: "#/components/examples/BaseDevice" + DeviceWithHardwareAddress: + $ref: "#/components/examples/DeviceWithHardwareAddress" + DeviceWithServiceSite: + $ref: "#/components/examples/DeviceWithServiceSite" + DeviceWithNetworks: + $ref: "#/components/examples/DeviceWithNetworks" + DeviceWithHardwareAddressAndServiceSite: + $ref: "#/components/examples/DeviceWithHardwareAddressAndServiceSite" + DeviceWithHardwareAddressAndNetworks: + $ref: "#/components/examples/DeviceWithHardwareAddressAndNetworks" + DeviceWithServiceSiteAndNetworks: + $ref: "#/components/examples/DeviceWithServiceSiteAndNetworks" + DeviceWithHardwareAddressAndServiceSiteAndNetworks: + $ref: "#/components/examples/DeviceWithHardwareAddressAndServiceSiteAndNetworks" + "400": + $ref: "#/components/responses/Generic400" + "401": + $ref: "#/components/responses/Generic401" + "403": + $ref: "#/components/responses/Generic403" + "404": + $ref: "#/components/responses/DeviceNotFound404" + "500": + $ref: "#/components/responses/Generic500" + "501": + $ref: "#/components/responses/Generic501" + "503": + $ref: "#/components/responses/Generic503" + + /devices/{deviceId}/isolated-networks: + get: + tags: + - Retrieve Isolated Network + summary: Get all networks configured on a device + security: + - openId: + - network-access-management:devices:read + - network-access-management:isolated-networks:read + operationId: getNetworksByDevice + description: | + Returns all networks configured on a device that matches the given ID. Scopes impact the output of this + endpoint. See the examples for various permutations. + + **Required Scopes:** + - **all of** + - **one of** + - `network-access-management:devices:read` + - `network-access-management:devices:write` + - `network-access-management:devices.hardware-address:read` + - **one of** + - `network-access-management:isolated-networks:read` + - `network-access-management:isolated-networks:write` + - `network-access-management:isolated-networks.primary:read` + - `network-access-management:isolated-networks.primary:write` + - `network-access-management:isolated-networks.auxiliary:read` + - `network-access-management:isolated-networks.auxiliary:write` + parameters: + - $ref: "#/components/parameters/deviceId" + responses: + "200": + description: Contains information about networks configured on the device + content: + application/json: + schema: + $ref: "#/components/schemas/NetworkList" + examples: + NetworkListWithDevices: + $ref: "#/components/examples/NetworkListWithDevices" + "400": + $ref: "#/components/responses/Generic400" + "401": + $ref: "#/components/responses/Generic401" + "403": + $ref: "#/components/responses/Generic403" + "404": + $ref: "#/components/responses/DeviceNotFound404" + "500": + $ref: "#/components/responses/Generic500" + "501": + $ref: "#/components/responses/Generic501" + "503": + $ref: "#/components/responses/Generic503" + + patch: + tags: + - Device Configure + summary: Bulk insert, remove or replace many networks from the configuration of a device + security: + - openId: + - network-access-management:devices:write + - network-access-management:isolated-networks:read + operationId: patchDeviceWithNetworks + description: | + Bulk inserts, removes, or replaces many networks from the configuration of the device by the given IDs. + + The replace option is intended to be used for networks that have a "removable" flag of `false`. When a network + is replaced and is no longer assigned to any device, it is considered automatically deleted. + + **Required Scopes:** + - **all of** + - `network-access-management:devices:write` + - **one of** + - `network-access-management:isolated-networks:read` + - `network-access-management:isolated-networks:write` + - `network-access-management:isolated-networks.primary:read` + - `network-access-management:isolated-networks.primary:write` + - `network-access-management:isolated-networks.auxiliary:read` + - `network-access-management:isolated-networks.auxiliary:write` + parameters: + - $ref: "#/components/parameters/deviceId" + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/BulkNetworkUpdate" + responses: + "204": + description: Successfully inserted, removed, or replaced the configuration for many networks on the device + "400": + $ref: "#/components/responses/NetworkNotRemovable400" + "401": + $ref: "#/components/responses/Generic401" + "403": + $ref: "#/components/responses/Generic403" + "404": + $ref: "#/components/responses/DeviceOrNetworkNotFound404" + "500": + $ref: "#/components/responses/Generic500" + "501": + $ref: "#/components/responses/Generic501" + "503": + $ref: "#/components/responses/Generic503" + + /isolated-networks: + get: + tags: + - Retrieve Isolated Network + summary: Get all Networks + security: + - openId: + - network-access-management:isolated-networks:read + operationId: getNetworks + description: | + Returns all networks. Scopes impact the output of this endpoint. See the examples for various permutations. + + ## With Default Device + **Required Scopes:** + - **one of** + - `network-access-management:isolated-networks:read` + - `network-access-management:isolated-networks:write` + - `network-access-management:isolated-networks.primary:read` + - `network-access-management:isolated-networks.primary:write` + - `network-access-management:isolated-networks.auxiliary:read` + - `network-access-management:isolated-networks.auxiliary:write` + + ## Without Default Device + **Required Scopes:** + - **all of** + - **one of** + - `network-access-management:isolated-networks:read` + - `network-access-management:isolated-networks:write` + - `network-access-management:isolated-networks.primary:read` + - `network-access-management:isolated-networks.primary:write` + - `network-access-management:isolated-networks.auxiliary:read` + - `network-access-management:isolated-networks.auxiliary:write` + - **one of** + - `network-access-management:devices:read` + - `network-access-management:devices:write` + - `network-access-management:devices.hardware-address:read` + responses: + "200": + description: Contains information about all networks + content: + application/json: + schema: + $ref: "#/components/schemas/NetworkList" + examples: + BaseNetworkList: + $ref: "#/components/examples/BaseNetworkList" + NetworkListWithDevices: + $ref: "#/components/examples/NetworkListWithDevices" + "401": + $ref: "#/components/responses/Generic401" + "403": + $ref: "#/components/responses/DefaultDeviceNotSupported403" + "500": + $ref: "#/components/responses/Generic500" + "501": + $ref: "#/components/responses/Generic501" + "503": + $ref: "#/components/responses/Generic503" + + post: + tags: + - Configure and Apply Isolated Network + summary: Create a new network + operationId: createNetwork + security: + - openId: + - network-access-management:isolated-networks:write + description: | + Creates and returns the new network. Scopes impact the function and output of this endpoint. See the examples + for various permutations. + + ## With Default Device + For eligible service owner's with a default device, create the network and configure it to the service owner's + one and only one device at their one and only one service location. The `devices` field MUST NOT be set or it + MUST be set to `undefined`. + + **Required Scopes:** + - **one of** + - `network-access-management:isolated-networks:write` + - `network-access-management:isolated-networks.primary:write` + - `network-access-management:isolated-networks.auxiliary:write` + + ## Without Default Device + Create the network and configure it to one or more devices. The `devices` field MUST NOT be empty. + + **Required Scopes:** + - **all of** + - `network-access-management:devices:write` + - **one of** + - `network-access-management:isolated-networks:write` + - `network-access-management:isolated-networks.primary:write` + - `network-access-management:isolated-networks.auxiliary:write` + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/NetworkCreate" + examples: + BaseNetworkCreate: + $ref: "#/components/examples/BaseNetworkCreate" + NetworkCreateWithDevices: + $ref: "#/components/examples/NetworkCreateWithDevices" + responses: + "201": + description: Contains information about the created network + content: + application/json: + schema: + $ref: "#/components/schemas/Network" + examples: + BaseNetwork: + $ref: "#/components/examples/BaseNetwork" + NetworkWithDevices: + $ref: "#/components/examples/NetworkWithDevices" + "400": + $ref: "#/components/responses/Generic400" + "401": + $ref: "#/components/responses/Generic401" + "403": + $ref: "#/components/responses/DefaultDeviceNotSupported403" + "500": + $ref: "#/components/responses/Generic500" + "501": + $ref: "#/components/responses/Generic501" + "503": + $ref: "#/components/responses/Generic503" + + /isolated-networks/{netId}: + get: + tags: + - Retrieve Isolated Network + summary: Get a Network by ID + security: + - openId: + - network-access-management:isolated-networks:read + operationId: getNetwork + description: | + Returns the network that matches the given ID. Scopes impact the output of this endpoint. See the examples for + various permutations. + + ## With Default Device + **Required Scopes:** + - **one of** + - `network-access-management:isolated-networks:read` + - `network-access-management:isolated-networks:write` + - `network-access-management:isolated-networks.primary:read` + - `network-access-management:isolated-networks.primary:write` + - `network-access-management:isolated-networks.auxiliary:read` + - `network-access-management:isolated-networks.auxiliary:write` + + ## Without Default Device + **Required Scopes:** + - **all of** + - **one of** + - `network-access-management:isolated-networks:read` + - `network-access-management:isolated-networks:write` + - `network-access-management:isolated-networks.primary:read` + - `network-access-management:isolated-networks.primary:write` + - `network-access-management:isolated-networks.auxiliary:read` + - `network-access-management:isolated-networks.auxiliary:write` + - **one of** + - `network-access-management:devices:read` + - `network-access-management:devices:write` + - `network-access-management:devices.hardware-address:read` + parameters: + - $ref: "#/components/parameters/netId" + responses: + "200": + description: Contains information about the network + content: + application/json: + schema: + $ref: "#/components/schemas/Network" + examples: + BaseNetwork: + $ref: "#/components/examples/BaseNetwork" + NetworkWithDevices: + $ref: "#/components/examples/NetworkWithDevices" + "400": + $ref: "#/components/responses/Generic400" + "401": + $ref: "#/components/responses/Generic401" + "403": + $ref: "#/components/responses/DefaultDeviceNotSupported403" + "404": + $ref: "#/components/responses/NetworkNotFound404" + "500": + $ref: "#/components/responses/Generic500" + "501": + $ref: "#/components/responses/Generic501" + "503": + $ref: "#/components/responses/Generic503" + + patch: + tags: + - Configure and Apply Isolated Network + summary: Update an existing network + security: + - openId: + - network-access-management:isolated-networks:write + operationId: updateNetwork + description: | + Updates the network, reconfigures any devices configured with the network, and returns the network that matches + the given ID. Scopes impact the output of this endpoint. See the examples for various permutations. + + ## With Default Device + **Required Scopes:** + - **one of** + - `network-access-management:isolated-networks:write` + - `network-access-management:isolated-networks.primary:write` + - `network-access-management:isolated-networks.auxiliary:write` + + ## Without Default Device + **Required Scopes:** + - **all of** + - `network-access-management:devices:write` + - **one of** + - `network-access-management:isolated-networks:write` + - `network-access-management:isolated-networks.primary:write` + - `network-access-management:isolated-networks.auxiliary:write` + parameters: + - $ref: "#/components/parameters/netId" + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/NetworkUpdate" + examples: + NetworkUpdate: + $ref: "#/components/examples/NetworkUpdate" + responses: + "200": + description: Contains information about the updated network + content: + application/json: + schema: + $ref: "#/components/schemas/Network" + examples: + BaseNetwork: + $ref: "#/components/examples/BaseNetwork" + NetworkWithDevices: + $ref: "#/components/examples/NetworkWithDevices" + "400": + $ref: "#/components/responses/Generic400" + "401": + $ref: "#/components/responses/Generic401" + "403": + $ref: "#/components/responses/DefaultDeviceNotSupported403" + "404": + $ref: "#/components/responses/NetworkNotFound404" + "500": + $ref: "#/components/responses/Generic500" + "501": + $ref: "#/components/responses/Generic501" + "503": + $ref: "#/components/responses/Generic503" + + delete: + tags: + - Configure and Apply Isolated Network + summary: Delete a network + security: + - openId: + - network-access-management:isolated-networks:write + operationId: deleteNetwork + description: | + Deletes the network and removes the configuration from any devices configured with the network that matches the + given ID. + + ## With Default Device + **Required Scopes:** + - **one of** + - `network-access-management:isolated-networks:write` + - `network-access-management:isolated-networks.primary:write` + - `network-access-management:isolated-networks.auxiliary:write` + + ## Without Default Device + **Required Scopes:** + - **all off** + - `network-access-management:devices:write` + - **one of** + - `network-access-management:isolated-networks:write` + - `network-access-management:isolated-networks.primary:write` + - `network-access-management:isolated-networks.auxiliary:write` + parameters: + - $ref: "#/components/parameters/netId" + responses: + "204": + description: Successfully deleted the network + "400": + $ref: "#/components/responses/NetworkNotRemovable400" + "401": + $ref: "#/components/responses/Generic401" + "403": + $ref: "#/components/responses/DefaultDeviceNotSupported403" + "404": + $ref: "#/components/responses/NetworkNotFound404" + "500": + $ref: "#/components/responses/Generic500" + "501": + $ref: "#/components/responses/Generic501" + "503": + $ref: "#/components/responses/Generic503" + + /isolated-networks/{netId}/devices: + get: + tags: + - Retrieve Device + summary: Get all devices configured with a network + security: + - openId: + - network-access-management:devices:read + - network-access-management:isolated-networks:read + operationId: getDevicesByNetwork + description: | + Returns all devices configured with a network that matches the given ID. Scopes impact the output of this + endpoint. See the examples for various permutations. + + **Required Scopes:** + - **all of** + - **one of** + - `network-access-management:devices:read` + - `network-access-management:devices:write` + - `network-access-management:devices.hardware-address:read` + - **one of** + - `network-access-management:isolated-networks:read` + - `network-access-management:isolated-networks:write` + - `network-access-management:isolated-networks.primary:read` + - `network-access-management:isolated-networks.primary:write` + - `network-access-management:isolated-networks.auxiliary:read` + - `network-access-management:isolated-networks.auxiliary:write` + + **Optional Scopes:** + - **one of** + - `network-access-management:service-sites:read` + - `network-access-management:service-sites.location:read` + parameters: + - $ref: "#/components/parameters/netId" + responses: + "200": + description: Contains information about devices configured with the network + content: + application/json: + schema: + $ref: "#/components/schemas/DeviceList" + examples: + DeviceListWithNetworks: + $ref: "#/components/examples/DeviceListWithNetworks" + DeviceListWithHardwareAddressAndNetworks: + $ref: "#/components/examples/DeviceListWithHardwareAddressAndNetworks" + DeviceListWithServiceSiteAndNetworks: + $ref: "#/components/examples/DeviceListWithServiceSiteAndNetworks" + DeviceListWithHardwareAddressAndServiceSiteAndNetworks: + $ref: "#/components/examples/DeviceListWithHardwareAddressAndServiceSiteAndNetworks" + "400": + $ref: "#/components/responses/Generic400" + "401": + $ref: "#/components/responses/Generic401" + "403": + $ref: "#/components/responses/Generic403" + "404": + $ref: "#/components/responses/NetworkNotFound404" + "500": + $ref: "#/components/responses/Generic500" + "501": + $ref: "#/components/responses/Generic501" + "503": + $ref: "#/components/responses/Generic503" + + patch: + tags: + - Device Configure + summary: Bulk insert, remove, or replace a network from the configuration of many devices + security: + - openId: + - network-access-management:devices:write + - network-access-management:isolated-networks:read + operationId: patchDevicesWithNetwork + description: | + Bulk inserts, removes, replaces a network from the configuration of many devices by the given IDs. + + **Required Scopes:** + - **all of ** + - `network-access-management:devices:write` + - **one of** + - `network-access-management:isolated-networks:read` + - `network-access-management:isolated-networks:write` + - `network-access-management:isolated-networks.primary:read` + - `network-access-management:isolated-networks.primary:write` + - `network-access-management:isolated-networks.auxiliary:read` + - `network-access-management:isolated-networks.auxiliary:write` + parameters: + - $ref: "#/components/parameters/netId" + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/BulkDeviceUpdate" + responses: + "204": + description: Successfully inserted, removed, or replaced the network from the configuration of many devices + "400": + $ref: "#/components/responses/NetworkNotRemovable400" + "401": + $ref: "#/components/responses/Generic401" + "403": + $ref: "#/components/responses/Generic403" + "404": + $ref: "#/components/responses/DeviceOrNetworkNotFound404" + "500": + $ref: "#/components/responses/Generic500" + "501": + $ref: "#/components/responses/Generic501" + "503": + $ref: "#/components/responses/Generic503" + + /reboot-requests: + get: + tags: + - Retrieve Reboot Request + summary: Get all Reboot Requests + security: + - openId: + - network-access-management:reboot-requests:read + operationId: getRebootRequests + description: | + Returns all reboot requests. Scopes impact the output of this endpoint. See the examples for various + permutations. + + ## With Default Device + **Required Scopes:** + - **one of** + - `network-access-management:reboot-requests:read` + - `network-access-management:reboot-requests:write` + + ## Without Default Device + **Required Scopes:** + - **all of** + - **one of** + - `network-access-management:reboot-requests:read` + - `network-access-management:reboot-requests:write` + - **one of** + - `network-access-management:devices:read` + - `network-access-management:devices:write` + - `network-access-management:devices.hardware-address:read` + responses: + "200": + description: Contains information about all reboot requests + content: + application/json: + schema: + $ref: "#/components/schemas/RebootRequestList" + examples: + BaseRebootRequestList: + $ref: "#/components/examples/BaseRebootRequestList" + RebootRequestListWithDevices: + $ref: "#/components/examples/RebootRequestListWithDevices" + "401": + $ref: "#/components/responses/Generic401" + "403": + $ref: "#/components/responses/DefaultDeviceNotSupported403" + "500": + $ref: "#/components/responses/Generic500" + "501": + $ref: "#/components/responses/Generic501" + "503": + $ref: "#/components/responses/Generic503" + + post: + tags: + - Configure Reboot Request + summary: Create a new reboot request + security: + - openId: + - network-access-management:reboot-requests:write + operationId: createRebootRequest + description: | + Creates and returns the new reboot request. Scopes impact the function and output of this endpoint. See the + examples for various permutations. + + ## With Default Device + Creates the reboot request and issues it to the service owner's one and only one device at their one and only + one service location. The `devices` field MUST NOT be set or it MUST be set to `undefined`. + + **Required Scopes:** + - **all of** + - `network-access-management:reboot-requests:write` + + ## Without Default Device + Creates the reboot request and issues it to one or more devices. The `devices` field MUST be set to a non-empty + `list of device IDs`. + + **Required Scopes:** + - **all of** + - `network-access-management:devices:write` + - `network-access-management:reboot-requests:write` + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/RebootRequestCreate" + examples: + BaseRebootRequestCreate: + $ref: "#/components/examples/BaseRebootRequestCreate" + RebootRequestCreateWithDevices: + $ref: "#/components/examples/RebootRequestCreateWithDevices" + responses: + "201": + description: Contains information about the created reboot request + content: + application/json: + schema: + $ref: "#/components/schemas/RebootRequest" + examples: + BaseRebootRequest: + $ref: "#/components/examples/BaseRebootRequest" + RebootRequestWithDevices: + $ref: "#/components/examples/RebootRequestWithDevices" + "400": + $ref: "#/components/responses/Generic400" + "401": + $ref: "#/components/responses/Generic401" + "403": + $ref: "#/components/responses/DefaultDeviceNotSupported403" + "500": + $ref: "#/components/responses/Generic500" + "501": + $ref: "#/components/responses/Generic501" + "503": + $ref: "#/components/responses/Generic503" + + /reboot-requests/{rebootId}: + get: + tags: + - Retrieve Reboot Request + summary: Get a Reboot Request by ID + security: + - openId: + - network-access-management:reboot-requests:read + operationId: getRebootRequest + description: | + Returns the reboot request that matches the given ID. Scopes impact the output of this endpoint. See the + examples for various permutations. + + ## With Default Device + **Required Scopes:** + - **one of** + - `network-access-management:reboot-requests:read` + - `network-access-management:reboot-requests:write` + + ## Without Default Device + **Required Scopes:** + - **all off** + - **one of** + - `network-access-management:reboot-requests:read` + - `network-access-management:reboot-requests:write` + - **one of** + - `network-access-management:devices:read` + - `network-access-management:devices:write` + - `network-access-management:devices.hardware-address:read` + parameters: + - $ref: "#/components/parameters/rebootId" + responses: + "200": + description: Contains information about the reboot request + content: + application/json: + schema: + $ref: "#/components/schemas/RebootRequest" + examples: + BaseRebootRequest: + $ref: "#/components/examples/BaseRebootRequest" + RebootRequestWithDevices: + $ref: "#/components/examples/RebootRequestWithDevices" + "400": + $ref: "#/components/responses/Generic400" + "401": + $ref: "#/components/responses/Generic401" + "403": + $ref: "#/components/responses/DefaultDeviceNotSupported403" + "404": + $ref: "#/components/responses/NetworkNotFound404" + "500": + $ref: "#/components/responses/Generic500" + "501": + $ref: "#/components/responses/Generic501" + "503": + $ref: "#/components/responses/Generic503" + + patch: + tags: + - Configure Reboot Request + summary: Update an existing reboot request + security: + - openId: + - network-access-management:reboot-requests:write + operationId: updateRebootRequest + description: | + Updates the reboot request, reboot for any devices targeted with the reboot request, and returns the reboot + request that matches the given ID. Scopes impact the output of this endpoint. See the examples for various + permutations. + + ## With Default Device + **Required Scopes:** + - **all of** + - `network-access-management:reboot-requests:write` + + ## Without Default Device + **Required Scopes:** + - **all of** + - `network-access-management:devices:write` + - `network-access-management:reboot-requests:write` + parameters: + - $ref: "#/components/parameters/rebootId" + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/RebootRequestUpdate" + examples: + RebootRequestUpdate: + $ref: "#/components/examples/RebootRequestUpdate" + responses: + "200": + description: Contains information about the updated reboot request + content: + application/json: + schema: + $ref: "#/components/schemas/RebootRequest" + examples: + BaseRebootRequest: + $ref: "#/components/examples/BaseRebootRequest" + RebootRequestWithDevices: + $ref: "#/components/examples/RebootRequestWithDevices" + "400": + $ref: "#/components/responses/Generic400" + "401": + $ref: "#/components/responses/Generic401" + "403": + $ref: "#/components/responses/DefaultDeviceNotSupported403" + "404": + $ref: "#/components/responses/NetworkNotFound404" + "500": + $ref: "#/components/responses/Generic500" + "501": + $ref: "#/components/responses/Generic501" + "503": + $ref: "#/components/responses/Generic503" + + delete: + tags: + - Configure Reboot Request + summary: Delete a reboot request + security: + - openId: + - network-access-management:reboot-requests:write + operationId: deleteRebootRequest + description: | + Deletes the reboot request that matches the given ID. + + ## With Default Device + **Required Scopes:** + - **all of** + - `network-access-management:reboot-requests:write` + + ## Without Default Device + **Required Scopes:** + - **all of** + - `network-access-management:devices:write` + - `network-access-management:reboot-requests:write` + parameters: + - $ref: "#/components/parameters/rebootId" + responses: + "204": + description: Successfully deleted the reboot request + "400": + $ref: "#/components/responses/Generic400" + "401": + $ref: "#/components/responses/Generic401" + "403": + $ref: "#/components/responses/DefaultDeviceNotSupported403" + "404": + $ref: "#/components/responses/NetworkNotFound404" + "500": + $ref: "#/components/responses/Generic500" + "501": + $ref: "#/components/responses/Generic501" + "503": + $ref: "#/components/responses/Generic503" + +components: + securitySchemes: + openId: + type: openIdConnect + openIdConnectUrl: https://example.com/.well-known/openid-configuration + + parameters: + siteId: + name: siteId + in: path + required: true + schema: + $ref: "#/components/schemas/ServiceSiteId" + description: ID of the service site to find + + deviceId: + name: deviceId + in: path + required: true + schema: + $ref: "#/components/schemas/DeviceId" + description: ID of the device to find + + netId: + name: netId + in: path + required: true + schema: + $ref: "#/components/schemas/DeviceId" + description: ID of the network to find + + rebootId: + name: rebootId + in: path + required: true + schema: + $ref: "#/components/schemas/RebootId" + description: ID of the reboot request to find + + schemas: + DateTime: + type: string + format: date-time + description: | + It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone. + Recommended format is yyyy-MM-dd'T'HH:mm:ss.SSSZ (i.e. which allows 2023-07-03T14:27:08.312+02:00 or + 2023-07-03T12:27:08.312Z) + example: &date-time "2023-07-03T14:27:08.312+02:00" + + ServiceSiteId: + type: string + minLength: 1 + maxLength: 64 + description: The unique identifier for a service site + example: &service-site-id "site-123" + + DeviceId: + type: string + minLength: 1 + maxLength: 64 + description: The unique identifier for a device + example: &device-id "device-1" + + DeviceIdList: + type: array + description: List of device IDs + items: + $ref: "#/components/schemas/DeviceId" + example: &device-id-list + - *device-id + - &device-id2 "device-2" + + NetworkId: + type: string + minLength: 1 + maxLength: 64 + description: The unique identifier for the network. + example: &network-id "wifi-1" + + NetworkIdList: + type: array + description: List of network IDs + items: + $ref: "#/components/schemas/NetworkId" + example: &network-id-list + - *network-id + - &network-id2 "wifi-2" + + NetworkVersion: + type: string + minLength: 1 + maxLength: 64 + description: The unique version for the network. + example: &network-version "1234ABCD" + + RebootId: + type: string + minLength: 1 + maxLength: 64 + description: The unique identifier for the reboot request. + example: &reboot-id "reboot-1" + + GeographicPoint: + type: object + properties: + latitude: + type: number + format: double + description: The latitude coordinate + example: &geographic-point-latitude 40.7128 + longitude: + type: number + format: double + description: The longitude coordinate + example: &geographic-point-longitude -74.0060 + elevation: + type: object + properties: + value: + type: number + format: double + description: The elevation value + example: &geographic-point-elevation-value 10.0 + units: + type: string + enum: [feet, meters] + description: The units of elevation (feet or meters) + example: &geographic-point-elevation-units "feet" + required: + - value + - units + example: &geographic-point-elevation + value: *geographic-point-elevation-value + units: *geographic-point-elevation-units + required: + - latitude + - longitude + example: &geographic-point + latitude: *geographic-point-latitude + longitude: *geographic-point-longitude + elevation: *geographic-point-elevation + + PropertyAddress: + type: object + externalDocs: + description: TMF673 Geographic Address Management API User Guide v4.0.0 + url: https://www.tmforum.org/resources/specification/tmf673-geographic-address-management-api-user-guide-v4-0-0/ + properties: + id: + type: string + description: The unique identifier for the property address + minLength: 1 + maxLength: 64 + example: &property-address-id "address-123" + addressLine1: + type: string + maxLength: 128 + description: The first line of the address + example: &property-address-address-line-1 "123 Main St" + addressLine2: + type: string + maxLength: 128 + description: The second line of the address + example: &property-address-address-line-2 "Suite 456" + streetNr: + type: string + maxLength: 64 + description: The street number + example: &property-address-street-nr "123" + streetNrSuffix: + type: string + maxLength: 64 + description: The suffix for the street number + example: &property-address-street-nr-suffix "A" + streetNrLast: + type: string + maxLength: 64 + description: The last street number + example: &property-address-street-nr-last "125" + streetNrLastSuffix: + type: string + maxLength: 64 + description: The suffix for the last street number + example: &property-address-street-nr-last-suffix "B" + streetName: + type: string + maxLength: 64 + description: The name of the street + example: &property-address-street-name "Main" + subUnitType: + type: string + maxLength: 64 + description: The type of sub-unit (e.g., Apartment, Suite) + example: &property-address-sub-unit-type "Apartment" + subUnitNr: + type: string + maxLength: 64 + description: The number of the sub-unit + example: &property-address-sub-unit-nr "A12" + levelType: + type: string + maxLength: 64 + description: The type of level (e.g., Floor, Basement) + example: &property-address-level-type "Floor" + levelNr: + type: string + maxLength: 64 + description: The number of the level + example: &property-address-level-nr "3" + buildingName: + type: string + maxLength: 64 + description: The name of the building + example: &property-address-building-name "Example Building" + privateStreetName: + type: string + maxLength: 64 + description: The name of a private street + example: &property-address-private-street-name "Private Rd" + locality: + type: string + maxLength: 64 + description: The locality (neighborhood, area) + example: &property-address-locality "Example Locality" + city: + type: string + maxLength: 128 + description: The city or town + example: &property-address-city "Example State" + stateOrProvince: + type: string + maxLength: 64 + description: The state or province + example: &property-address-state-or-province "EX" + country: + type: string + maxLength: 64 + description: The country + example: &property-address-country "United States" + postCode: + type: string + maxLength: 64 + description: The postal code or ZIP code + example: &property-address-post-code "12345" + postCodeExtension: + type: string + maxLength: 64 + description: The postal code extension + example: &property-address-post-code-extension "6789" + example: &property-address + id: *property-address-id + addressLine1: *property-address-address-line-1 + addressLine2: *property-address-address-line-2 + streetNr: *property-address-street-nr + streetNrSuffix: *property-address-street-nr-suffix + streetNrLast: *property-address-street-nr-last + streetNrLastSuffix: *property-address-street-nr-last-suffix + streetName: *property-address-street-name + subUnitType: *property-address-sub-unit-type + subUnitNr: *property-address-sub-unit-nr + levelType: *property-address-level-type + levelNr: *property-address-level-nr + buildingName: *property-address-building-name + privateStreetName: *property-address-private-street-name + locality: *property-address-locality + city: *property-address-city + stateOrProvince: *property-address-state-or-province + country: *property-address-country + postCode: *property-address-post-code + postCodeExtension: *property-address-post-code-extension + + ServiceSite: + type: object + properties: + id: + $ref: "#/components/schemas/ServiceSiteId" + name: + type: string + maxLength: 64 + example: &service-site-name "Example Service Site 1" + description: + type: string + maxLength: 64 + example: &service-site-description "This is the first example service site" + devices: + allOf: + - description: The IDs of devices located at this service site + - $ref: "#/components/schemas/DeviceIdList" + location: + type: object + properties: + geographicPoint: + $ref: "#/components/schemas/GeographicPoint" + propertyAddress: + $ref: "#/components/schemas/PropertyAddress" + example: &service-site-location + geographicPoint: *geographic-point + propertyAddress: *property-address + required: + - id + example: &service-site + id: *service-site-id + name: *service-site-name + description: *service-site-description + devices: *device-id-list + location: *service-site-location + + ServiceSiteList: + type: array + items: + $ref: "#/components/schemas/ServiceSite" + example: &service-site-list + - *service-site + - id: &service-site-id2 "site-456" + name: &service-site-name2 "Example Service Site 2" + description: &service-site-description2 "This is the second example service site" + devices: &service-site-devices2 + - "device-3" + - "device-4" + location: &service-site-location2 + geographicPoint: + latitude: 41.8781 + longitude: -87.6298 + elevation: + value: 5.0 + units: "meters" + propertyAddress: + id: "address-2" + addressLine1: "456 Elm St" + streetNr: "456" + streetName: "Elm" + locality: "Another Locality" + city: "Another City" + stateOrProvince: "AY" + country: "Another Country" + postCode: "67890" + + NetworkRole: + description: >- + Role of the network on a device. + type: string + enum: [primary, auxiliary] + default: "auxiliary" + example: &network-role "primary" + + NetworkDeviceConfiguration: + type: object + description: >- + A specific network configuration with an implied network to configure on a specific network access device with + specified role. + properties: + device: + description: "ID of the device with the network" + allOf: + - $ref: "#/components/schemas/DeviceId" + - example: *device-id + role: + description: >- + Role of the network on the device. Defaults to "auxiliary" if unspecified. + default: "auxiliary" + allOf: + - $ref: "#/components/schemas/NetworkRole" + - example: *network-role + required: ["device"] + example: &network-device-configuration + device: *device-id + role: *network-role + + NetworkDeviceReplacement: + type: object + description: >- + A specific network configuration with an implied network to replace an existing network on specific network + access device. + properties: + device: + description: "ID of the device with the network" + allOf: + - $ref: "#/components/schemas/DeviceId" + - example: *device-id + replace: + description: >- + Network to replace on the device. + allOf: + - $ref: "#/components/schemas/NetworkId" + - example: *network-id + required: ["device", "replace"] + example: &network-device-replacement + device: *device-id + replace: *network-id + + NetworkDeviceIntersectionCreate: + type: object + description: | + Properties of a specific network configuration with an implied network on a specific network access device. + properties: + intersectionType: + type: string + enum: ["NetworkDeviceRoleConfiguration", "NetworkDeviceReplacement"] + example: &network-device-intersection-type "NetworkDeviceRoleConfiguration" + required: + - intersectionType + discriminator: + propertyName: intersectionType + mappings: + - NetworkDeviceRoleConfiguration: "#/components/schemas/NetworkDeviceRoleConfiguration" + - NetworkDeviceReplacement: "#/components/schemas/NetworkDeviceReplacement" + example: &network-device-intersection-create + intersectionType: *network-device-intersection-type + device: *device-id + role: *network-role + + NetworkDeviceIntersectionCreateList: + type: array + items: + $ref: "#/components/schemas/NetworkDeviceIntersectionCreate" + example: &network-device-intersection-create-list + - *network-device-intersection-create + - &network-device-intersection-create-2 + intersectionType: &network-device-intersection-type-2 "NetworkDeviceReplacement" + device: *device-id2 + replace: *network-id2 + + NetworkDeviceIntersection: + allOf: + - $ref: "#/components/schemas/NetworkDeviceConfiguration" + - description: >- + Properties of a specific network configuration with an implied network on a specific network access device. + properties: + removable: + type: boolean + description: >- + Flag indicating if the network can be removed. Defaults to `true` if unspecified. + default: true + example: &network-removable false + required: + - device + example: &network-device-intersection + device: *device-id + role: *network-role + removable: *network-removable + + NetworkDeviceIntersectionList: + type: array + items: + $ref: "#/components/schemas/NetworkDeviceIntersection" + example: &network-device-intersection-list + - *network-device-intersection + + DeviceNetworkIntersection: + type: object + description: >- + Properties of a specific network configuration on a specific network access device with an implied device. + properties: + network: + description: "ID of the network." + allOf: + - $ref: "#/components/schemas/NetworkId" + - example: *network-id + role: + description: >- + Role of the network. Defaults to "auxiliary" if unspecified. + default: "auxiliary" + allOf: + - $ref: "#/components/schemas/NetworkRole" + - example: *network-role + removable: + type: boolean + description: >- + Flag indicating if the network can be removed. Defaults to `true` if unspecified. + default: true + example: *network-removable + required: + - network + example: &device-network-intersection + network: *network-id + role: *network-role + removable: *network-removable + + DeviceNetworkIntersectionList: + type: array + items: + $ref: "#/components/schemas/DeviceNetworkIntersection" + example: &device-network-intersection-list + - *device-network-intersection + + Device: + type: object + properties: + id: + $ref: "#/components/schemas/DeviceId" + name: + type: string + minLength: 1 + maxLength: 100 + description: The name of the device + example: &device-name "Gateway-1" + description: + type: string + minLength: 0 + maxLength: 255 + description: A description of the device + example: &device-description "A Wi-Fi gateway device" + hardwareAddress: + description: The hardware address of the device + oneOf: + - type: object + properties: + hardwareAddressType: + type: string + enum: ["EUI-48"] + example: &device-hardware-address-type "EUI-48" + value: + type: string + pattern: "^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$" + example: &device-hardware-address-value "12:34:56:78:9A:BC" + required: + - hardwareAddressType + - value + discriminator: + propertyName: hardwareAddressType + example: &device-hardware-address + hardwareAddressType: *device-hardware-address-type + value: *device-hardware-address-value + serviceSite: + $ref: "#/components/schemas/ServiceSiteId" + networks: + allOf: + - $ref: "#/components/schemas/DeviceNetworkIntersectionList" + - description: The IDs of networks attached to the device + example: *device-network-intersection-list + maxAuxiliaryNetworks: + type: integer + description: >- + Maximum amount of auxiliary networks the device supports for a given client. For the `only-own` client + roles, this is a count of what is in-use by the client + remaining count of what the client can create. For + `primary`-only client roles, the field is not used. For `auxiliary`-only client roles, it is the maximum + number the device supports. + minimum: 1 + example: &device-max-networks 2 + required: + - id + example: &device + id: *device-id + name: *device-name + description: *device-description + hardwareAddress: *device-hardware-address + serviceSite: *service-site-id + networks: *device-network-intersection-list + maxAuxiliaryNetworks: *device-max-networks + + DeviceList: + type: array + items: + $ref: "#/components/schemas/Device" + example: &device-list + - *device + - id: *device-id2 + name: &device-name2 "Gateway-2" + description: &device-description2 "A second Wi-Fi gateway devices" + hardwareAddress: &device-hardware-address2 + hardwareAddressType: "EUI-48" + value: "AB:CD:EF:12:34:56" + serviceSite: *service-site-id2 + networks: *device-network-intersection-list + maxAuxiliaryNetworks: &device-max-networks2 2 + + WpaPersonalDetail: + type: object + properties: + password: + type: string + maxLength: 255 + description: The password for the WPA Personal Wi-Fi network + example: &wpa-personal-password "my-password" + securityModeType: + type: string + enum: + - WPA2-Personal + - WPA2-WPA3-Personal + - WPA3-Personal + description: | + The security mode type for the WPA Personal Wi-Fi network. + Leave blank to auto-select. + example: &wpa-personal-security-mode-type "WPA3-Personal" + required: + - password + example: &wpa-personal + password: *wpa-personal-password + securityModeType: *wpa-personal-security-mode-type + + WpaEnterpriseDetail: + type: object + properties: + authServer: + type: string + maxLength: 255 + description: The authentication server for the WPA Enterprise Wi-Fi network + example: &wpa-enterprise-auth-server "1.2.3.4" + securityModeType: + type: string + enum: + - WPA2-Enterprise + - WPA3-Enterprise + description: The security mode type for the WPA Enterprise Wi-Fi network + example: &wpa-enterprise-security-mode-type "WPA3-Enterprise" + required: + - securityModeType + example: &wpa-enterprise + authServer: *wpa-enterprise-auth-server + securityModeType: *wpa-enterprise-security-mode-type + + WiFiAccessDetail: + type: object + properties: + accessType: + type: string + enum: + - Wi-Fi + example: &wifi-access-detail-access-type "Wi-Fi" + ssid: + type: string + minLength: 2 + maxLength: 32 + description: The SSID (network name) of the Wi-Fi network + example: &wifi-access-detail-ssid "my-ssid" + securityMode: + oneOf: + - $ref: "#/components/schemas/WpaPersonalDetail" + - $ref: "#/components/schemas/WpaEnterpriseDetail" + discriminator: + propertyName: securityModeType + mapping: + WPA2-Personal: "#/components/schemas/WpaPersonalDetail" + WPA2-WPA3-Personal: "#/components/schemas/WpaPersonalDetail" + WPA3-Personal: "#/components/schemas/WpaPersonalDetail" + WPA2-Enterprise: "#/components/schemas/WpaEnterpriseDetail" + WPA3-Enterprise: "#/components/schemas/WpaEnterpriseDetail" + description: The security mode details for the Wi-Fi network + example: *wpa-personal + required: + - accessType + example: &wifi-access-detail + accessType: *wifi-access-detail-access-type + ssid: *wifi-access-detail-ssid + securityMode: *wpa-personal + + AccessDetail: + oneOf: + - $ref: "#/components/schemas/WiFiAccessDetail" + discriminator: + propertyName: accessType + mapping: + Wi-Fi: "#/components/schemas/WiFiAccessDetail" + example: *wifi-access-detail + + NetworkUpdate: + type: object + properties: + description: + type: string + maxLength: 255 + description: A description of the network + example: &network-description "my network" + accessDetail: + description: The access details for the network + allOf: + - $ref: "#/components/schemas/AccessDetail" + - example: *wifi-access-detail + expiration: + allOf: + - $ref: "#/components/schemas/DateTime" + - description: | + The expiration date and time of the network. It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) + and must have time zone. Recommended format is yyyy-MM-dd'T'HH:mm:ss.SSSZ (i.e. which allows + 2023-07-03T14:27:08.312+02:00 or 2023-07-03T12:27:08.312Z). + example: &network-update + description: *network-description + accessDetail: *wifi-access-detail + expiration: *date-time + + NetworkCreate: + allOf: + - $ref: "#/components/schemas/NetworkUpdate" + - properties: + devices: + allOf: + - $ref: "#/components/schemas/NetworkDeviceIntersectionCreateList" + - minLength: 1 + description: >- + List of network role and device pairs to configure the created network. + example: + - *network-device-intersection-create-list + required: + - accessDetail + example: &network-create + description: *network-description + accessDetail: *wifi-access-detail + expiration: *date-time + devices: *network-device-intersection-create-list + + Network: + allOf: + - $ref: "#/components/schemas/NetworkUpdate" + - properties: + id: + $ref: "#/components/schemas/NetworkId" + devices: + allOf: + - $ref: "#/components/schemas/NetworkDeviceIntersectionList" + - minLength: 1 + description: >- + List of devices the network is configured on. + example: + - *network-device-intersection-create-list + createdAt: + allOf: + - $ref: "#/components/schemas/DateTime" + - description: | + The creation date and time of the network. It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) + and must have time zone. Recommended format is yyyy-MM-dd'T'HH:mm:ss.SSSZ (i.e. which allows + 2023-07-03T14:27:08.312+02:00 or 2023-07-03T12:27:08.312Z). + createdBy: + type: string + maxLength: 100 + description: The user who created the network + example: &network-created-by "user-1" + modifiedAt: + allOf: + - $ref: "#/components/schemas/DateTime" + - description: | + The last update date and time of the network. It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) + and must have time zone. Recommended format is yyyy-MM-dd'T'HH:mm:ss.SSSZ (i.e. which allows + 2023-07-03T14:27:08.312+02:00 or 2023-07-03T12:27:08.312Z). + modifiedBy: + type: string + maxLength: 100 + description: The user who last updated the network + example: &network-modified-by "user-2" + version: + $ref: "#/components/schemas/NetworkVersion" + required: + - id + - accessDetail + example: &network + id: *network-id + description: *network-description + accessDetail: *wifi-access-detail + expiration: *date-time + devices: *network-device-intersection-list + createdAt: *date-time + createdBy: *network-created-by + modifiedAt: *date-time + modifiedBy: *network-modified-by + version: *network-version + + NetworkList: + type: array + items: + $ref: "#/components/schemas/Network" + example: &network-list + - *network + - id: *network-id2 + description: &network-description2 "my second network" + accessDetail: &network-access-detail2 + accessType: "Wi-Fi" + ssid: "my-second-ssid" + securityMode: + password: "my-other-password" + securityModeType: "WPA2-Personal" + expiration: *date-time + devices: &network-device-intersection-list2 + - device: *device-id2 + role: &network-role2 "auxiliary" + createdAt: *date-time + createdBy: &network-created-by2 "user-3" + modifiedAt: *date-time + modifiedBy: &network-modified-by2 "user-4" + version: &network-version2 "0000FFFF" + + DeviceNetworkReplacement: + type: object + description: | + A device network replacement operation. + properties: + device: + allOf: + - $ref: "#/components/schemas/DeviceId" + - example: *device-id + replace: + allOf: + - $ref: "#/components/schemas/NetworkId" + - example: *network-id + required: + - device + - replace + example: &device-network-replacement + device: "device-4" + replace: "wifi-5" + + DeviceNetworkReplacementList: + type: array + items: + $ref: "#/components/schemas/DeviceNetworkReplacement" + example: &device-network-replacement-list + - *device-network-replacement + + BulkDeviceUpdate: + type: object + description: | + Update a set of devices by inserting or deleting devices by ID from that set. + properties: + insert: + allOf: + - $ref: "#/components/schemas/DeviceIdList" + - example: *device-id-list + delete: + allOf: + - $ref: "#/components/schemas/DeviceIdList" + - example: &bulk-device-update-delete + - "device-3" + replace: + allOf: + - $ref: "#/components/schemas/DeviceNetworkReplacementList" + - example: *device-network-replacement-list + example: &bulk-device-update + insert: *device-id-list + delete: *bulk-device-update-delete + replace: *device-network-replacement-list + + NetworkReplacement: + type: object + description: | + A network replacement operation. + properties: + replace: + allOf: + - $ref: "#/components/schemas/NetworkId" + - example: *network-id + with: + allOf: + - $ref: "#/components/schemas/NetworkId" + - example: *network-id2 + required: + - replace + - with + example: &network-replacement + replace: "wifi-4" + with: "wifi-5" + + NetworkReplacementList: + type: array + items: + $ref: "#/components/schemas/NetworkReplacement" + example: &network-replacement-list + - *network-replacement + + BulkNetworkUpdate: + type: object + description: | + Update a set of networks by inserting, deleting, or replacing networks by ID from that set. + properties: + insert: + allOf: + - $ref: "#/components/schemas/NetworkIdList" + - example: *network-id-list + delete: + allOf: + - $ref: "#/components/schemas/NetworkIdList" + - example: &bulk-network-update-delete + - "wifi-3" + replace: + description: List of network replacements. + allOf: + - $ref: "#/components/schemas/NetworkReplacementList" + - example: *network-replacement-list + example: &bulk-network-update + insert: *network-id-list + delete: *bulk-network-update-delete + replace: *network-replacement-list + + RebootRequestUpdate: + type: object + properties: + message: + type: string + maxLength: 255 + description: A message related to the reboot request + example: &reboot-message "reboot to correct performance" + atTime: + allOf: + - $ref: "#/components/schemas/DateTime" + - description: | + The date and time to reboot the device. Do not include 'atTime' to request immediate reboot. It must + follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone. + Recommended format is yyyy-MM-dd'T'HH:mm:ss.SSSZ (i.e. which allows 2023-07-03T14:27:08.312+02:00 or + 2023-07-03T12:27:08.312Z). + example: &reboot-request-update + message: *reboot-message + atTime: *date-time + + RebootRequestCreate: + allOf: + - $ref: "#/components/schemas/RebootRequestUpdate" + - properties: + devices: + type: array + items: + $ref: "#/components/schemas/DeviceId" + description: >- + List of devices to reboot. When undefined, the reboot targets the 'default' device (simple use case that + wouldn't use locations or devices). Throws an error when creating if there is no 'default' device. + example: *device-id-list + example: &reboot-create + message: *reboot-message + atTime: *date-time + devices: *device-id-list + + RebootRequest: + allOf: + - $ref: "#/components/schemas/RebootRequestCreate" + - properties: + id: + $ref: "#/components/schemas/RebootId" + createdAt: + allOf: + - $ref: "#/components/schemas/DateTime" + - description: | + The creation date and time of the reboot request. It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) + and must have time zone. Recommended format is yyyy-MM-dd'T'HH:mm:ss.SSSZ (i.e. which allows + 2023-07-03T14:27:08.312+02:00 or 2023-07-03T12:27:08.312Z). + createdBy: + type: string + maxLength: 100 + description: The user who created the reboot request + example: &reboot-created-by "user-1" + modifiedAt: + allOf: + - $ref: "#/components/schemas/DateTime" + - description: | + The last update date and time of the reboot request. It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) + and must have time zone. Recommended format is yyyy-MM-dd'T'HH:mm:ss.SSSZ (i.e. which allows + 2023-07-03T14:27:08.312+02:00 or 2023-07-03T12:27:08.312Z). + modifiedBy: + type: string + maxLength: 100 + description: The user who last updated the reboot request + example: &reboot-modified-by "user-2" + required: + - id + example: &reboot-request + id: *reboot-id + message: *reboot-message + atTime: *date-time + devices: *device-id-list + createdAt: *date-time + createdBy: *reboot-created-by + modifiedAt: *date-time + modifiedBy: *reboot-modified-by + + RebootRequestList: + type: array + items: + $ref: "#/components/schemas/RebootRequest" + example: &reboot-request-list + - *reboot-request + - id: &reboot-id2 "reboot-2" + message: &reboot-message2 "my second reboot request" + atTime: *date-time + devices: &reboot-devices2 + - "device-3" + - "device-4" + createdAt: *date-time + createdBy: &reboot-created-by2 "user-3" + modifiedAt: *date-time + modifiedBy: &reboot-modified-by2 "user-4" + + ErrorInfo: + type: object + properties: + status: + type: integer + description: HTTP status code returned along with this error response + code: + type: string + description: Code given to this error + message: + type: string + description: Detailed error description + required: + - status + - code + - message + + examples: + BaseServiceSite: + summary: Base Service Site + description: | + Output with the following scope(s): + - `network-access-management:service-sites:read` + value: &base-service-site + id: *service-site-id + + ServiceSiteWithLocation: + summary: Service Site with Location + description: | + Output with the following scope(s): + - `network-access-management:service-sites.location:read` + value: &service-site-with-location + id: *service-site-id + name: *service-site-name + description: *service-site-description + location: *service-site-location + + ServiceSiteWithDevices: + summary: Service Site with Devices + description: | + Output with the following scope(s): + - **all of** + - `network-access-management:service-sites:read` + - **one of** + - `network-access-management:devices:read` + - `network-access-management:devices:write` + - `network-access-management:devices.hardware-address:read` + value: &service-site-with-devices + id: *service-site-id + devices: *device-id-list + + ServiceSiteWithLocationAndDevices: + summary: Service Site with Location and Devices + description: | + Output with the following scope(s): + - **all of** + - `network-access-management:service-sites.location:read` + - **one of** + - `network-access-management:devices:read` + - `network-access-management:devices:write` + - `network-access-management:devices.hardware-address:read` + value: *service-site + + BaseServiceSiteList: + summary: Base Service Site List + description: | + Output with the following scope(s): + - **all of** + - `network-access-management:service-sites:read` + value: + - *base-service-site + - id: *service-site-id2 + + ServiceSiteListWithLocation: + summary: Service Site List with Location + description: | + Output with the following scope(s): + - **all of** + - `network-access-management:service-sites.location:read` + value: + - *service-site-with-location + - id: *service-site-id2 + name: *service-site-name2 + description: *service-site-description2 + location: *service-site-location2 + + ServiceSiteListWithDevices: + summary: Service Site List with Devices + description: | + Output with the following scope(s): + - **all of** + - `network-access-management:service-sites:read` + - **one of** + - `network-access-management:devices:read` + - `network-access-management:devices:write` + - `network-access-management:devices.hardware-address:read` + value: + - *service-site-with-devices + - id: *service-site-id2 + devices: *service-site-devices2 + + ServiceSiteListWithLocationAndDevices: + summary: Service Site List with Location and Devices + description: | + Output with the following scope(s): + - **all of** + - `network-access-management:service-sites.location:read` + - **one of** + - `network-access-management:devices:read` + - `network-access-management:devices:write` + - `network-access-management:devices.hardware-address:read` + value: *service-site-list + + BaseDevice: + summary: Base Device + description: | + Output with the following scope(s): + - **one of** + - `network-access-management:devices:read` + - `network-access-management:devices:write` + value: &base-device + id: *device-id + name: *device-name + description: *device-description + + DeviceWithHardwareAddress: + summary: Device with Hardware Address + description: | + Output with the following scope(s): + - **all of** + - `network-access-management:devices.hardware-address:read` + value: &device-with-hardware-address + id: *device-id + name: *device-name + description: *device-description + hardwareAddress: *device-hardware-address + + DeviceWithServiceSite: + summary: Device with Service Site + description: | + Output with the following scope(s): + - **all of** + - **one of** + - `network-access-management:devices:read` + - `network-access-management:devices:write` + - **one of** + - `network-access-management:service-sites:read` + - `network-access-management:service-sites.location:read` + value: &device-with-service-site + id: *device-id + name: *device-name + description: *device-description + serviceSite: *service-site-id + + DeviceWithNetworks: + summary: Device with Networks + description: | + Output with the following scope(s): + - **all of** + - **one of** + - `network-access-management:devices:read` + - `network-access-management:devices:write` + - **one of** + - `network-access-management:isolated-networks:read` + - `network-access-management:isolated-networks:write` + - `network-access-management:isolated-networks.primary:read` + - `network-access-management:isolated-networks.primary:write` + - `network-access-management:isolated-networks.auxiliary:read` + - `network-access-management:isolated-networks.auxiliary:write` + value: &device-with-networks + id: *device-id + name: *device-name + description: *device-description + networks: *device-network-intersection-list + maxAuxiliaryNetworks: *device-max-networks + + DeviceWithHardwareAddressAndServiceSite: + summary: Device with Hardware Address and Service Site + description: | + Output with the following scope(s): + - **all of** + - `network-access-management:devices.hardware-address:read` + - **one of** + - `network-access-management:service-sites:read` + - `network-access-management:service-sites.location:read` + value: &device-with-hardware-address-and-service-site + id: *device-id + name: *device-name + description: *device-description + hardwareAddress: *device-hardware-address + serviceSite: *service-site-id + + DeviceWithHardwareAddressAndNetworks: + summary: Device with Hardware Address and Networks + description: | + Output with the following scope(s): + - **all of** + - `network-access-management:devices.hardware-address:read` + - **one of** + - `network-access-management:isolated-networks:read` + - `network-access-management:isolated-networks:write` + - `network-access-management:isolated-networks.primary:read` + - `network-access-management:isolated-networks.primary:write` + - `network-access-management:isolated-networks.auxiliary:read` + - `network-access-management:isolated-networks.auxiliary:write` + value: &device-with-hardware-address-and-networks + id: *device-id + name: *device-name + description: *device-description + hardwareAddress: *device-hardware-address + networks: *device-network-intersection-list + maxAuxiliaryNetworks: *device-max-networks + + DeviceWithServiceSiteAndNetworks: + summary: Device with Service Site and Networks + description: | + Output with the following scope(s): + - **all of** + - **one of** + - `network-access-management:devices:read` + - `network-access-management:devices:write` + - **one of** + - `network-access-management:service-sites:read` + - `network-access-management:service-sites.location:read` + - **one of** + - `network-access-management:isolated-networks:read` + - `network-access-management:isolated-networks:write` + - `network-access-management:isolated-networks.primary:read` + - `network-access-management:isolated-networks.primary:write` + - `network-access-management:isolated-networks.auxiliary:read` + - `network-access-management:isolated-networks.auxiliary:write` + value: &device-with-service-site-and-networks + id: *device-id + name: *device-name + description: *device-description + serviceSite: *service-site-id + networks: *device-network-intersection-list + maxAuxiliaryNetworks: *device-max-networks + + DeviceWithHardwareAddressAndServiceSiteAndNetworks: + summary: Device with Hardware Address, Service Site, and Networks + description: | + Output with the following scope(s): + - **all of** + - `network-access-management:devices.hardware-address:read` + - **one of** + - `network-access-management:service-sites:read` + - `network-access-management:service-sites.location:read` + - **one of** + - `network-access-management:isolated-networks:read` + - `network-access-management:isolated-networks:write` + - `network-access-management:isolated-networks.primary:read` + - `network-access-management:isolated-networks.primary:write` + - `network-access-management:isolated-networks.auxiliary:read` + - `network-access-management:isolated-networks.auxiliary:write` + value: *device + + BaseDeviceList: + summary: Base Device List + description: | + Output with the following scope(s): + - **one of** + - `network-access-management:devices:read` + - `network-access-management:devices:write` + value: + - *base-device + - id: *device-id2 + name: *device-name2 + description: *device-description2 + + DeviceListWithHardwareAddress: + summary: Device List with Hardware Address + description: | + Output with the following scope(s): + - **all of** + - `network-access-management:devices.hardware-address:read` + value: + - *device-with-hardware-address + - id: *device-id2 + name: *device-name2 + description: *device-description2 + hardwareAddress: *device-hardware-address2 + + DeviceListWithServiceSite: + summary: Device List with Service Site + description: | + Output with the following scope(s): + - **all of** + - **one of** + - `network-access-management:devices:read` + - `network-access-management:devices:write` + - **one of** + - `network-access-management:service-sites:read` + - `network-access-management:service-sites.location:read` + value: + - *device-with-service-site + - id: *device-id2 + name: *device-name2 + description: *device-description2 + serviceSite: *service-site-id2 + + DeviceListWithNetworks: + summary: Device List with Networks + description: | + Output with the following scope(s): + - **all of** + - **one of** + - `network-access-management:devices:read` + - `network-access-management:devices:write` + - **one of** + - `network-access-management:isolated-networks:read` + - `network-access-management:isolated-networks:write` + - `network-access-management:isolated-networks.primary:read` + - `network-access-management:isolated-networks.primary:write` + - `network-access-management:isolated-networks.auxiliary:read` + - `network-access-management:isolated-networks.auxiliary:write` + value: + - *device-with-networks + - id: *device-id2 + name: *device-name2 + description: *device-description2 + networks: *device-network-intersection-list + maxAuxiliaryNetworks: *device-max-networks2 + + DeviceListWithHardwareAddressAndServiceSite: + summary: Device List with Hardware Address and Service Site + description: | + Output with the following scope(s): + - **all of** + - `network-access-management:devices.hardware-address:read` + - **one of** + - `network-access-management:service-sites:read` + - `network-access-management:service-sites.location:read` + value: + - *device-with-hardware-address-and-service-site + - id: *device-id2 + name: *device-name2 + description: *device-description2 + hardwareAddress: *device-hardware-address2 + serviceSite: *service-site-id2 + + DeviceListWithHardwareAddressAndNetworks: + summary: Device List with Hardware Address and Networks + description: | + Output with the following scope(s): + - **all of** + - `network-access-management:devices.hardware-address:read` + - **one of** + - `network-access-management:isolated-networks:read` + - `network-access-management:isolated-networks:write` + - `network-access-management:isolated-networks.primary:read` + - `network-access-management:isolated-networks.primary:write` + - `network-access-management:isolated-networks.auxiliary:read` + - `network-access-management:isolated-networks.auxiliary:write` + value: + - *device-with-hardware-address-and-networks + - id: *device-id2 + name: *device-name2 + description: *device-description2 + hardwareAddress: *device-hardware-address2 + networks: *device-network-intersection-list + maxAuxiliaryNetworks: *device-max-networks2 + + DeviceListWithServiceSiteAndNetworks: + summary: Device List with Service Site and Networks + description: | + Output with the following scope(s): + - **all of** + - **one of** + - `network-access-management:devices:read` + - `network-access-management:devices:write` + - **one of** + - `network-access-management:service-sites:read` + - `network-access-management:service-sites.location:read` + - **one of** + - `network-access-management:isolated-networks:read` + - `network-access-management:isolated-networks:write` + - `network-access-management:isolated-networks.primary:read` + - `network-access-management:isolated-networks.primary:write` + - `network-access-management:isolated-networks.auxiliary:read` + - `network-access-management:isolated-networks.auxiliary:write` + value: + - *device-with-service-site-and-networks + - id: *device-id2 + name: *device-name2 + description: *device-description2 + serviceSite: *service-site-id2 + networks: *device-network-intersection-list + maxAuxiliaryNetworks: *device-max-networks2 + + DeviceListWithHardwareAddressAndServiceSiteAndNetworks: + summary: Device List with Hardware Address, Service Site, and Networks + description: | + Output with the following scope(s): + - **all of** + - `network-access-management:devices.hardware-address:read` + - **one of** + - `network-access-management:service-sites:read` + - `network-access-management:service-sites.location:read` + - **one of** + - `network-access-management:isolated-networks:read` + - `network-access-management:isolated-networks:write` + - `network-access-management:isolated-networks.primary:read` + - `network-access-management:isolated-networks.primary:write` + - `network-access-management:isolated-networks.auxiliary:read` + - `network-access-management:isolated-networks.auxiliary:write` + value: *device-list + + BaseNetwork: + summary: Network Configuration with Default Device + description: | + Output with the following scope(s): + - **one of** + - `network-access-management:isolated-networks:read` + - `network-access-management:isolated-networks:write` + - `network-access-management:isolated-networks.primary:read` + - `network-access-management:isolated-networks.primary:write` + - `network-access-management:isolated-networks.auxiliary:read` + - `network-access-management:isolated-networks.auxiliary:write` + value: &base-network + id: *network-id + description: *network-description + accessDetail: *wifi-access-detail + expiration: *date-time + createdAt: *date-time + createdBy: *network-created-by + modifiedAt: *date-time + modifiedBy: *network-modified-by + version: *network-version + + NetworkWithDevices: + summary: Network Configuration + description: | + Output with the following scope(s): + - **all of** + - **one of** + - `network-access-management:isolated-networks:read` + - `network-access-management:isolated-networks:write` + - `network-access-management:isolated-networks.primary:read` + - `network-access-management:isolated-networks.primary:write` + - `network-access-management:isolated-networks.auxiliary:read` + - `network-access-management:isolated-networks.auxiliary:write` + - **one of** + - `network-access-management:devices:read` + - `network-access-management:devices:write` + - `network-access-management:devices.hardware-address:read` + value: *network + + NetworkUpdate: + summary: Network Update + description: | + Post with the following scope(s): + - **one of** + - `network-access-management:isolated-networks:write` + - `network-access-management:isolated-networks.primary:write` + - `network-access-management:isolated-networks.auxiliary:write` + value: *network-update + + BaseNetworkCreate: + summary: Create Network on Default Device + description: | + Post with the following scope(s): + - **one of** + - `network-access-management:isolated-networks:write` + - `network-access-management:isolated-networks.primary:write` + - `network-access-management:isolated-networks.auxiliary:write` + value: + description: *network-description + accessDetail: *wifi-access-detail + expiration: *date-time + + NetworkCreateWithDevices: + summary: Create Network on Devices + description: | + Post with the following scope(s): + - **all of** + - `network-access-management:devices:write` + - **one of** + - `network-access-management:isolated-networks:write` + - `network-access-management:isolated-networks.primary:write` + - `network-access-management:isolated-networks.auxiliary:write` + value: *network-create + + BaseNetworkList: + summary: Network List with Default Device + description: | + Output with the following scope(s): + - **one of** + - `network-access-management:isolated-networks:read` + - `network-access-management:isolated-networks:write` + - `network-access-management:isolated-networks.primary:read` + - `network-access-management:isolated-networks.primary:write` + - `network-access-management:isolated-networks.auxiliary:read` + - `network-access-management:isolated-networks.auxiliary:write` + value: + - *base-network + - id: *network-id2 + description: *network-description2 + accessDetail: *network-access-detail2 + expiration: *date-time + createdAt: *date-time + createdBy: *date-time + modifiedAt: *date-time + modifiedBy: *network-modified-by2 + version: *network-version2 + + NetworkListWithDevices: + summary: Network List with Devices + description: | + Output with the following scope(s): + - **all of** + - **one of** + - `network-access-management:isolated-networks:read` + - `network-access-management:isolated-networks:write` + - `network-access-management:isolated-networks.primary:read` + - `network-access-management:isolated-networks.primary:write` + - `network-access-management:isolated-networks.auxiliary:read` + - `network-access-management:isolated-networks.auxiliary:write` + - **one of** + - `network-access-management:devices:read` + - `network-access-management:devices:write` + - `network-access-management:devices.hardware-address:read` + value: *network-list + + BaseRebootRequest: + summary: Reboot Request with Default Device + description: | + Output with the following scope(s): + - **one of** + - `network-access-management:reboot-requests:read` + - `network-access-management:reboot-requests:write` + value: &base-reboot-request + id: *reboot-id + message: *reboot-message + atTime: *date-time + createdAt: *date-time + createdBy: *reboot-created-by + modifiedAt: *date-time + modifiedBy: *reboot-modified-by + + RebootRequestWithDevices: + summary: Reboot Request + description: | + Output with the following scope(s): + - **all of** + - **one of** + - `network-access-management:reboot-requests:read` + - `network-access-management:reboot-requests:write` + - **one of** + - `network-access-management:devices:read` + - `network-access-management:devices:write` + - `network-access-management:devices.hardware-address:read` + value: *reboot-request + + RebootRequestUpdate: + summary: Reboot Request Update + description: | + Post with the following scope(s): + - **one of** + - `network-access-management:reboot-requests:write` + value: *reboot-request-update + + BaseRebootRequestCreate: + summary: Create Reboot Request for Default Device + description: | + Post with the following scope(s): + - **all of** + - `network-access-management:reboot-requests:write` + value: &reboot-request-update + message: *reboot-message + atTime: *date-time + + RebootRequestCreateWithDevices: + summary: Create Reboot Request for Devices + description: | + Post with the following scope(s): + - **all of** + - `network-access-management:devices:write` + - `network-access-management:reboot-requests:write` + value: *reboot-create + + BaseRebootRequestList: + summary: Reboot Request List with Default Device + description: | + Output with the following scope(s): + - **one of** + - `network-access-management:reboot-requests:read` + - `network-access-management:reboot-requests:write` + value: + - *base-reboot-request + - id: *reboot-id2 + message: *reboot-message2 + atTime: *date-time + createdAt: *date-time + createdBy: *reboot-created-by2 + modifiedAt: *date-time + modifiedBy: *reboot-modified-by2 + + RebootRequestListWithDevices: + summary: Reboot Request List + description: | + Output with the following scope(s): + - **all of** + - **one of** + - `network-access-management:reboot-requests:read` + - `network-access-management:reboot-requests:write` + - **one of** + - `network-access-management:devices:read` + - `network-access-management:devices:write` + - `network-access-management:devices.hardware-address:read` + value: *reboot-request-list + + responses: + Generic400: + description: Invalid input + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: &generic-400-example + status: 400 + code: INVALID_ARGUMENT + message: "Schema validation failed: ..." + + NetworkNotRemovable400: + description: Network not removable + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + NetworkNotRemovable: + summary: Network Not Removable Error + description: | + Output when attempting to delete or remove a network that can only be replaced. + value: + status: 400 + code: NETWORK_NOT_REMOVABLE + message: "Network not removable: ..." + Generic: + summary: Invalid Argument + value: *generic-400-example + + Generic401: + description: Unauthorized + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + status: 401 + code: UNAUTHENTICATED + message: "Authorization failed: ..." + + Generic403: + description: Forbidden + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: &generic-403-example + status: 403 + code: PERMISSION_DENIED + message: "Operation not allowed: ..." + + DefaultDeviceNotSupported403: + description: Default device not supported + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + DefaultDeviceNotSupported: + summary: Default Device Not Supported Error + description: | + Output with scopes for a default device but for an unsupported resource owner. + value: + status: 403 + code: DEFAULT_DEVICE_NOT_SUPPORTED + message: "Default device not supported: ..." + Generic: + summary: Forbidden + value: *generic-403-example + + ServiceSiteNotFound404: + description: Service site(s) not found + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + status: 404 + code: NOT_FOUND + message: "Service site ID(s) do not exist: [...]" + + DeviceNotFound404: + description: Device(s) not found + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + status: 404 + code: NOT_FOUND + message: "Device ID(s) do not exist: [...]" + + NetworkNotFound404: + description: Network(s) not found + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + status: 404 + code: NOT_FOUND + message: "Network ID(s) do not exist: [...]" + + DeviceOrNetworkNotFound404: + description: Device(s) and/or network(s) not found + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + status: 404 + code: NOT_FOUND + message: "Device ID(s) do not exist: [...]; Network ID(s) do not exist: [...]" + + Generic500: + description: Internal server error + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + status: 500 + code: INTERNAL_SERVER_ERROR + message: "Internal server error: ..." + + Generic501: + description: Not Implemented + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + status: 501 + code: NOT_IMPLEMENTED + message: "Service not implemented for the specified endpoint" + + Generic503: + description: Service unavailable + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + example: + status: 503 + code: SERVICE_UNAVAILABLE + message: "Service unavailable"