From c32ab7920f00e5f8febee5e2576be750767e0ad9 Mon Sep 17 00:00:00 2001 From: Christopher Aubut Date: Wed, 5 Jun 2024 11:18:30 -0600 Subject: [PATCH 01/30] chore: adds initial proposal from the backlog working group --- .../network_access_management.yaml | 2863 +++++++++++++++++ 1 file changed, 2863 insertions(+) create mode 100644 code/API_definitions/network_access_management.yaml diff --git a/code/API_definitions/network_access_management.yaml b/code/API_definitions/network_access_management.yaml new file mode 100644 index 0000000..c169f7f --- /dev/null +++ b/code/API_definitions/network_access_management.yaml @@ -0,0 +1,2863 @@ +openapi: 3.0.3 + +info: + title: CPE Management API + version: 0.0.1 + 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. OAuth 2.0 is used for authorizing an identity (resource holder) and scopes are used for role-based authorization. + + ## Authorization + Authorization of API clients SHOULD be performed with OAuth 2.0 using the authorization code grant type such that service owners delegate access to their resources exposed by this API to the API client. PKCE MUST be used when the API client secret cannot be secured (e.g., mobile application or single page application without a secure back-end). This API MAY also be used with the client credentials grant type, though such a use case only makes sense for first-party network operator API clients or when the service owner operates their own API client (client ID is bound to the service owner's identity). + + ### Scopes + OAuth 2.0 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 + |-------|-------------|--------- + | **cpe-management-service-sites-read** | List a service owner's service sites + | **cpe-management-service-sites-location-read** | Read a service site's physical location | cpe-management-service-sites-read + | **cpe-management-devices-read** | List a service owner's devices + | **cpe-management-devices-hardware-address-read** | Read a service owner's device's hardware address | cpe-management-devices-read + | **cpe-management-devices-write** | Modify which networks are configured on a service owner's devices | cpe-management-devices-read + | **cpe-management-isolated-networks-read** | List a service owner's isolated networks created by the calling API client + | **cpe-management-isolated-networks-write** | Create or modify a service owner's isolated networks created by the calling API client | cpe-management-isolated-networks-read + | **cpe-management-isolated-networks-primary-read** | Access information about a service owner's primary isolated network + | **cpe-management-isolated-networks-primary-write** | Modify a service owner's primary isolated network | cpe-management-isolated-networks-primary-read + | **cpe-management-isolated-networks-auxiliary-read** | List a service owner's auxiliary isolated networks | cpe-management-isolated-networks-read + | **cpe-management-isolated-networks-auxiliary-write** | Create or modify a service owner's auxiliary isolated networks | cpe-management-isolated-networks-auxiliary-read
cpe-management-isolated-networks-write + | **cpe-management-reboot-requests-read** | List a service owner's reboot requests created by the calling API client + | **cpe-management-reboot-requests-write** | Create or modify a service owner's reboot request created by the calling API client | cpe-management-reboot-request-read + + ### Claims + OAuth 2.0 claims are not used by this API to allow for the use of JSON Web Encryption (JWE) access tokens. + + ## 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 OAuth 2.0 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. + + license: + name: Apache 2.0 + url: https://www.apache.org/licenses/LICENSE-2.0 + contact: + email: project-manager@cablelabs.com + +tags: + - name: Service Sites + - name: Devices + - name: Isolated Networks + - name: Reboot Requests + +servers: + - url: "{apiRoot}/{basePath}" + variables: + apiRoot: + default: http://localhost:5000 + description: API root + basePath: + default: cpe-management/v0 + description: Base path for the CPE Management API + +security: + - oauth2: [] + +paths: + /service-sites: + get: + tags: + - Service Sites + summary: Get all service sites + security: + - oauth2: + - cpe-management-service-sites-read + - cpe-management-service-sites-location-read + - cpe-management-devices-read + operationId: getServiceSites + description: | + Returns all service sites. Scopes impact the output of this endpoint. See the examples for various permutations. + + **Required Scopes:** + - **any of** + - `cpe-management-service-sites-read` + - `cpe-management-service-sites-location-read` + + **Optional Scopes:** + - `cpe-management-devices-read` + - `cpe-management-devices-write` + - `cpe-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: + - Service Sites + summary: Get a service site by ID + security: + - oauth2: + - cpe-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:** + - **any of** + - `cpe-management-service-sites-read` + - `cpe-management-service-sites-location-read` + + **Optional Scopes:** + - `cpe-management-devices-read` + - `cpe-management-devices-write` + - `cpe-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: + - Service Sites + - Devices + summary: Get all devices at the service site + security: + - oauth2: + - cpe-management-service-sites-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:** + - **any of** + - `cpe-management-service-sites-read` + - `cpe-management-service-sites-location-read` + - **any of** + - `cpe-management-devices-read` + - `cpe-management-devices-write` + - `cpe-management-devices-hardware-address-read` + + **Optional Scopes:** + - `cpe-management-isolated-networks-read` + - `cpe-management-isolated-networks-write` + - `cpe-management-isolated-networks-primary-read` + - `cpe-management-isolated-networks-primary-write` + - `cpe-management-isolated-networks-auxiliary-read` + - `cpe-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: + - Service Sites + - Isolated Networks + summary: Get all networks at a service site + operationId: getNetworksByServiceSite + description: | + Returns all networks at a service site that matches the given ID. + + **Required Scopes:** + - **any of** + - `cpe-management-service-sites-read` + - `cpe-management-service-sites-location-read` + - **any of** + - `cpe-management-devices-read` + - `cpe-management-devices-write` + - `cpe-management-devices-hardware-address-read` + - **any of** + - `cpe-management-isolated-networks-read` + - `cpe-management-isolated-networks-write` + - `cpe-management-isolated-networks-primary-read` + - `cpe-management-isolated-networks-primary-write` + - `cpe-management-isolated-networks-auxiliary-read` + - `cpe-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: + - Devices + summary: Get all devices + operationId: getDevices + description: | + Returns all devices. Scopes impact the output of this endpoint. See the examples for various permutations. + + **Required Scopes:** + - **any of** + - `cpe-management-devices-read` + - `cpe-management-devices-write` + - `cpe-management-devices-hardware-address-read` + + **Optional Scopes:** + - **any of** + - `cpe-management-service-sites-read` + - `cpe-management-service-sites-location-read` + - `cpe-management-isolated-networks-read` + - `cpe-management-isolated-networks-write` + - `cpe-management-isolated-networks-primary-read` + - `cpe-management-isolated-networks-primary-write` + - `cpe-management-isolated-networks-auxiliary-read` + - `cpe-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}: + parameters: + - $ref: "#/components/parameters/deviceId" + get: + tags: + - Devices + summary: Get a device by ID + 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:** + - **any of** + - `cpe-management-devices-read` + - `cpe-management-devices-write` + - `cpe-management-devices-hardware-address-read` + + **Optional Scopes:** + - **any of** + - `cpe-management-service-sites-read` + - `cpe-management-service-sites-location-read` + - `cpe-management-isolated-networks-read` + - `cpe-management-isolated-networks-write` + - `cpe-management-isolated-networks-primary-read` + - `cpe-management-isolated-networks-primary-write` + - `cpe-management-isolated-networks-auxiliary-read` + - `cpe-management-isolated-networks-auxiliary-write` + 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: + parameters: + - $ref: "#/components/parameters/deviceId" + get: + tags: + - Devices + - Isolated Networks + summary: Get all networks configured on a device + 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:** + - **any of** + - `cpe-management-devices-read` + - `cpe-management-devices-write` + - `cpe-management-devices-hardware-address-read` + - **any of** + - `cpe-management-isolated-networks-read` + - `cpe-management-isolated-networks-write` + - `cpe-management-isolated-networks-primary-read` + - `cpe-management-isolated-networks-primary-write` + - `cpe-management-isolated-networks-auxiliary-read` + - `cpe-management-isolated-networks-auxiliary-write` + 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: + - Devices + - Isolated Networks + summary: Bulk insert, remove or replace many networks from the configuration of a device + 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:** + - `cpe-management-devices-write` + - **any of** + - `cpe-management-isolated-networks-read` + - `cpe-management-isolated-networks-write` + - `cpe-management-isolated-networks-primary-read` + - `cpe-management-isolated-networks-primary-write` + - `cpe-management-isolated-networks-auxiliary-read` + - `cpe-management-isolated-networks-auxiliary-write` + 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: + - Isolated Networks + summary: Get all Networks + operationId: getNetworks + description: | + Returns all networks. Scopes impact the output of this endpoint. See the examples for various permutations. + + ## With Default Device + **Required Scopes:** + - **any of** + - `cpe-management-isolated-networks-read` + - `cpe-management-isolated-networks-write` + - `cpe-management-isolated-networks-primary-read` + - `cpe-management-isolated-networks-primary-write` + - `cpe-management-isolated-networks-auxiliary-read` + - `cpe-management-isolated-networks-auxiliary-write` + + ## Without Default Device + **Required Scopes:** + - **any of** + - `cpe-management-isolated-networks-read` + - `cpe-management-isolated-networks-write` + - `cpe-management-isolated-networks-primary-read` + - `cpe-management-isolated-networks-primary-write` + - `cpe-management-isolated-networks-auxiliary-read` + - `cpe-management-isolated-networks-auxiliary-write` + - **any of** + - `cpe-management-devices-read` + - `cpe-management-devices-write` + - `cpe-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: + - Isolated Networks + summary: Create a new network + operationId: createNetwork + 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:** + - **any of** + - `cpe-management-isolated-networks-write` + - `cpe-management-isolated-networks-primary-write` + - `cpe-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:** + - `cpe-management-devices-write` + - **any of** + - `cpe-management-isolated-networks-write` + - `cpe-management-isolated-networks-primary-write` + - `cpe-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: + - Isolated Networks + summary: Get a Network by ID + 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:** + - **any of** + - `cpe-management-isolated-networks-read` + - `cpe-management-isolated-networks-write` + - `cpe-management-isolated-networks-primary-read` + - `cpe-management-isolated-networks-primary-write` + - `cpe-management-isolated-networks-auxiliary-read` + - `cpe-management-isolated-networks-auxiliary-write` + + ## Without Default Device + **Required Scopes:** + - **any of** + - `cpe-management-isolated-networks-read` + - `cpe-management-isolated-networks-write` + - `cpe-management-isolated-networks-primary-read` + - `cpe-management-isolated-networks-primary-write` + - `cpe-management-isolated-networks-auxiliary-read` + - `cpe-management-isolated-networks-auxiliary-write` + - **any of** + - `cpe-management-devices-read` + - `cpe-management-devices-write` + - `cpe-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: + - Isolated Networks + summary: Update an existing network + 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:** + - **any of** + - `cpe-management-isolated-networks-write` + - `cpe-management-isolated-networks-primary-write` + - `cpe-management-isolated-networks-auxiliary-write` + + ## Without Default Device + **Required Scopes:** + - `cpe-management-devices-write` + - **any of** + - `cpe-management-isolated-networks-write` + - `cpe-management-isolated-networks-primary-write` + - `cpe-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: + - Isolated Networks + summary: Delete a network + 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:** + - **any of** + - `cpe-management-isolated-networks-write` + - `cpe-management-isolated-networks-primary-write` + - `cpe-management-isolated-networks-auxiliary-write` + + ## Without Default Device + **Required Scopes:** + - `cpe-management-devices-write` + - **any of** + - `cpe-management-isolated-networks-write` + - `cpe-management-isolated-networks-primary-write` + - `cpe-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: + parameters: + - $ref: "#/components/parameters/netId" + get: + tags: + - Devices + - Isolated Networks + summary: Get all devices configured with a network + 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:** + - **any of** + - `cpe-management-devices-read` + - `cpe-management-devices-write` + - `cpe-management-devices-hardware-address-read` + - **any of** + - `cpe-management-isolated-networks-read` + - `cpe-management-isolated-networks-write` + - `cpe-management-isolated-networks-primary-read` + - `cpe-management-isolated-networks-primary-write` + - `cpe-management-isolated-networks-auxiliary-read` + - `cpe-management-isolated-networks-auxiliary-write` + + **Optional Scopes:** + - **any of** + - `cpe-management-service-sites-read` + - `cpe-management-service-sites-location-read` + 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: + - Devices + - Isolated Networks + summary: Bulk insert, remove, or replace a network from the configuration of many devices + operationId: patchDevicesWithNetwork + description: | + Bulk inserts, removes, replaces a network from the configuration of many devices by the given IDs. + + **Required Scopes:** + - `cpe-management-devices-write` + - **any of** + - `cpe-management-isolated-networks-read` + - `cpe-management-isolated-networks-write` + - `cpe-management-isolated-networks-primary-read` + - `cpe-management-isolated-networks-primary-write` + - `cpe-management-isolated-networks-auxiliary-read` + - `cpe-management-isolated-networks-auxiliary-write` + 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: + - Reboot Requests + summary: Get all Reboot Requests + 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:** + - **any of** + - `cpe-management-reboot-requests-read` + - `cpe-management-reboot-requests-write` + + ## Without Default Device + **Required Scopes:** + - **any of** + - `cpe-management-reboot-requests-read` + - `cpe-management-reboot-requests-write` + - **any of** + - `cpe-management-devices-read` + - `cpe-management-devices-write` + - `cpe-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: + - Reboot Requests + summary: Create a new reboot request + 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:** + - **any of** + - `cpe-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:** + - `cpe-management-devices-write` + - **any of** + - `cpe-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: + - Reboot Requests + summary: Get a Reboot Request by ID + 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:** + - **any of** + - `cpe-management-reboot-requests-read` + - `cpe-management-reboot-requests-write` + + ## Without Default Device + **Required Scopes:** + - **any of** + - `cpe-management-reboot-requests-read` + - `cpe-management-reboot-requests-write` + - **any of** + - `cpe-management-devices-read` + - `cpe-management-devices-write` + - `cpe-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: + - Reboot Requests + summary: Update an existing reboot request + 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:** + - **any of** + - `cpe-management-reboot-requests-write` + + ## Without Default Device + **Required Scopes:** + - `cpe-management-devices-write` + - **any of** + - `cpe-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: + - Reboot Requests + summary: Delete a reboot request + operationId: deleteRebootRequest + description: | + Deletes the reboot request that matches the given ID. + + ## With Default Device + **Required Scopes:** + - **any of** + - `cpe-management-reboot-requests-write` + + ## Without Default Device + **Required Scopes:** + - `cpe-management-devices-write` + - **any of** + - `cpe-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: + oauth2: + type: oauth2 + description: This API uses OAuth 2 with the authorization code grant type flow + flows: + authorizationCode: + authorizationUrl: "https://api.example.com/oauth2/authorize" + tokenUrl: &token-url "https://api.example.com/oauth2/token" + refreshUrl: &token-refresh-url "https://api.example.com/refresh" + scopes: &scopes + cpe-management-service-sites-read: List a service owner's service sites + cpe-management-service-sites-location-read: Read a service site's physical location + cpe-management-devices-read: List a service owner's devices + cpe-management-devices-hardware-address-read: Read a service owner's device's hardware address + cpe-management-devices-write: Modify which networks are configured on a service owner's devices + cpe-management-isolated-networks-read: List a service owner's isolated networks created by the calling API client + cpe-management-isolated-networks-write: Create or modify a service owner's isolated networks created by the calling API client + cpe-management-isolated-networks-primary-read: Access information about a service owner's primary isolated network + cpe-management-isolated-networks-primary-write: Modify a service owner's primary isolated network + cpe-management-isolated-networks-auxiliary-read: List service owner's auxiliary isolated networks + cpe-management-isolated-networks-auxiliary-write: Create or modify a service owner's auxiliary isolated networks + cpe-management-reboot-requests-read: List a service owner's reboot requests created by the calling API client + cpe-management-reboot-requests-write: Create or modify a service owner's reboot request created by the calling API client + clientCredentials: + tokenUrl: *token-url + refreshUrl: *token-refresh-url + scopes: *scopes + + 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: + 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" + + NetworkDeviceIntersectionCreate: + type: object + description: >- + Properties of a specific network configuration with an implied network on a specific network access device. + oneOf: + - required: ["device", "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", "replace"] + 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 + example: &network-device-intersection-create + 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 + device: *device-id2 + replace: *network-id2 + + NetworkDeviceIntersection: + allOf: + - $ref: "#/components/schemas/NetworkDeviceIntersectionCreate" + 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: + type: string + format: date-time + description: The expiration date and time of the network + example: &network-expiration "1970-01-03T00:00:00.000Z" + example: &network-update + description: *network-description + accessDetail: *wifi-access-detail + expiration: *network-expiration + + 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: *network-expiration + 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: + type: string + format: date-time + description: The creation date and time of the network + example: &network-created "1970-01-01T00:00:00.000Z" + createdBy: + type: string + maxLength: 100 + description: The user who created the network + example: &network-created-by "user-1" + modifiedAt: + type: string + format: date-time + description: The last update date and time of the network + example: &network-modified "1970-01-02T00:00:00.000Z" + 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: *network-expiration + devices: *network-device-intersection-list + createdAt: *network-created + createdBy: *network-created-by + modifiedAt: *network-modified + 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: &network-expiration2 "2023-08-25T00:42:17.272Z" + devices: &network-device-intersection-list2 + - device: *device-id2 + role: &network-role2 "auxiliary" + createdAt: &network-created-at2 "2023-08-25T00:42:17.272Z" + createdBy: &network-created-by2 "user-3" + modifiedAt: &network-modified-at2 "2023-08-25T00:42:17.272Z" + 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: + type: string + format: date-time + description: The date and time to reboot the device. Do not include 'atTime' to request immediate reboot. + example: &reboot-at-time "1970-01-03T00:00:00.000Z" + example: &reboot-request-update + message: *reboot-message + atTime: *reboot-at-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: *reboot-at-time + devices: *device-id-list + + RebootRequest: + allOf: + - $ref: "#/components/schemas/RebootRequestCreate" + properties: + id: + $ref: "#/components/schemas/RebootId" + createdAt: + type: string + format: date-time + description: The creation date and time of the reboot request + example: &reboot-created "1970-01-01T00:00:00.000Z" + createdBy: + type: string + maxLength: 100 + description: The user who created the reboot request + example: &reboot-created-by "user-1" + modifiedAt: + type: string + format: date-time + description: The last update date and time of the reboot request + example: &reboot-modified "1970-01-02T00:00:00.000Z" + 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: *reboot-at-time + devices: *device-id-list + createdAt: *reboot-created + createdBy: *reboot-created-by + modifiedAt: *reboot-modified + 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: &reboot-at-time2 "2023-08-25T00:42:17.272Z" + devices: &reboot-devices2 + - "device-3" + - "device-4" + createdAt: &reboot-created-at2 "2023-08-25T00:42:17.272Z" + createdBy: &reboot-created-by2 "user-3" + modifiedAt: &reboot-modified-at2 "2023-08-25T00:42:17.272Z" + 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): + - `cpe-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): + - `cpe-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): + - `cpe-management-service-sites-read` + - **any of** + - `cpe-management-devices-read` + - `cpe-management-devices-write` + - `cpe-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): + - `cpe-management-service-sites-location-read` + - **any of** + - `cpe-management-devices-read` + - `cpe-management-devices-write` + - `cpe-management-devices-hardware-address-read` + value: *service-site + + BaseServiceSiteList: + summary: Base Service Site List + description: | + Output with the following scope(s): + - `cpe-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): + - `cpe-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): + - `cpe-management-service-sites-read` + - **any of** + - `cpe-management-devices-read` + - `cpe-management-devices-write` + - `cpe-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): + - `cpe-management-service-sites-location-read` + - **any of** + - `cpe-management-devices-read` + - `cpe-management-devices-write` + - `cpe-management-devices-hardware-address-read` + value: *service-site-list + + BaseDevice: + summary: Base Device + description: | + Output with the following scope(s): + - **any of** + - `cpe-management-devices-read` + - `cpe-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): + - `cpe-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): + - **any of** + - `cpe-management-devices-read` + - `cpe-management-devices-write` + - **any of** + - `cpe-management-service-sites-read` + - `cpe-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): + - **any of** + - `cpe-management-devices-read` + - `cpe-management-devices-write` + - **any of** + - `cpe-management-isolated-networks-read` + - `cpe-management-isolated-networks-write` + - `cpe-management-isolated-networks-primary-read` + - `cpe-management-isolated-networks-primary-write` + - `cpe-management-isolated-networks-auxiliary-read` + - `cpe-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): + - `cpe-management-devices-hardware-address-read` + - **any of** + - `cpe-management-service-sites-read` + - `cpe-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): + - `cpe-management-devices-hardware-address-read` + - **any of** + - `cpe-management-isolated-networks-read` + - `cpe-management-isolated-networks-write` + - `cpe-management-isolated-networks-primary-read` + - `cpe-management-isolated-networks-primary-write` + - `cpe-management-isolated-networks-auxiliary-read` + - `cpe-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): + - **any of** + - `cpe-management-devices-read` + - `cpe-management-devices-write` + - **any of** + - `cpe-management-service-sites-read` + - `cpe-management-service-sites-location-read` + - **any of** + - `cpe-management-isolated-networks-read` + - `cpe-management-isolated-networks-write` + - `cpe-management-isolated-networks-primary-read` + - `cpe-management-isolated-networks-primary-write` + - `cpe-management-isolated-networks-auxiliary-read` + - `cpe-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): + - `cpe-management-devices-hardware-address-read` + - **any of** + - `cpe-management-service-sites-read` + - `cpe-management-service-sites-location-read` + - **any of** + - `cpe-management-isolated-networks-read` + - `cpe-management-isolated-networks-write` + - `cpe-management-isolated-networks-primary-read` + - `cpe-management-isolated-networks-primary-write` + - `cpe-management-isolated-networks-auxiliary-read` + - `cpe-management-isolated-networks-auxiliary-write` + value: *device + + BaseDeviceList: + summary: Base Device List + description: | + Output with the following scope(s): + - **any of** + - `cpe-management-devices-read` + - `cpe-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): + - `cpe-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): + - **any of** + - `cpe-management-devices-read` + - `cpe-management-devices-write` + - **any of** + - `cpe-management-service-sites-read` + - `cpe-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): + - **any of** + - `cpe-management-devices-read` + - `cpe-management-devices-write` + - **any of** + - `cpe-management-isolated-networks-read` + - `cpe-management-isolated-networks-write` + - `cpe-management-isolated-networks-primary-read` + - `cpe-management-isolated-networks-primary-write` + - `cpe-management-isolated-networks-auxiliary-read` + - `cpe-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): + - `cpe-management-devices-hardware-address-read` + - **any of** + - `cpe-management-service-sites-read` + - `cpe-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): + - `cpe-management-devices-hardware-address-read` + - **any of** + - `cpe-management-isolated-networks-read` + - `cpe-management-isolated-networks-write` + - `cpe-management-isolated-networks-primary-read` + - `cpe-management-isolated-networks-primary-write` + - `cpe-management-isolated-networks-auxiliary-read` + - `cpe-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): + - **any of** + - `cpe-management-devices-read` + - `cpe-management-devices-write` + - **any of** + - `cpe-management-service-sites-read` + - `cpe-management-service-sites-location-read` + - **any of** + - `cpe-management-isolated-networks-read` + - `cpe-management-isolated-networks-write` + - `cpe-management-isolated-networks-primary-read` + - `cpe-management-isolated-networks-primary-write` + - `cpe-management-isolated-networks-auxiliary-read` + - `cpe-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): + - `cpe-management-devices-hardware-address-read` + - **any of** + - `cpe-management-service-sites-read` + - `cpe-management-service-sites-location-read` + - **any of** + - `cpe-management-isolated-networks-read` + - `cpe-management-isolated-networks-write` + - `cpe-management-isolated-networks-primary-read` + - `cpe-management-isolated-networks-primary-write` + - `cpe-management-isolated-networks-auxiliary-read` + - `cpe-management-isolated-networks-auxiliary-write` + value: *device-list + + BaseNetwork: + summary: Network Configuration with Default Device + description: | + Output with the following scope(s): + - **any of** + - `cpe-management-isolated-networks-read` + - `cpe-management-isolated-networks-write` + - `cpe-management-isolated-networks-primary-read` + - `cpe-management-isolated-networks-primary-write` + - `cpe-management-isolated-networks-auxiliary-read` + - `cpe-management-isolated-networks-auxiliary-write` + value: &base-network + id: *network-id + description: *network-description + accessDetail: *wifi-access-detail + expiration: *network-expiration + createdAt: *network-created + createdBy: *network-created-by + modifiedAt: *network-modified + modifiedBy: *network-modified-by + version: *network-version + + NetworkWithDevices: + summary: Network Configuration + description: | + Output with the following scope(s): + - **any of** + - `cpe-management-isolated-networks-read` + - `cpe-management-isolated-networks-write` + - `cpe-management-isolated-networks-primary-read` + - `cpe-management-isolated-networks-primary-write` + - `cpe-management-isolated-networks-auxiliary-read` + - `cpe-management-isolated-networks-auxiliary-write` + - **any of** + - `cpe-management-devices-read` + - `cpe-management-devices-write` + - `cpe-management-devices-hardware-address-read` + value: *network + + NetworkUpdate: + summary: Network Update + description: | + Post with the following scope(s): + - **any of** + - `cpe-management-isolated-networks-write` + - `cpe-management-isolated-networks-primary-write` + - `cpe-management-isolated-networks-auxiliary-write` + value: *network-update + + BaseNetworkCreate: + summary: Create Network on Default Device + description: | + Post with the following scope(s): + - **any of** + - `cpe-management-isolated-networks-write` + - `cpe-management-isolated-networks-primary-write` + - `cpe-management-isolated-networks-auxiliary-write` + value: + description: *network-description + accessDetail: *wifi-access-detail + expiration: *network-expiration + + NetworkCreateWithDevices: + summary: Create Network on Devices + description: | + Post with the following scope(s): + - **any of** + - `cpe-management-isolated-networks-write` + - `cpe-management-isolated-networks-primary-write` + - `cpe-management-isolated-networks-auxiliary-write` + - `cpe-management-devices-write` + value: *network-create + + BaseNetworkList: + summary: Network List with Default Device + description: | + Output with the following scope(s): + - **any of** + - `cpe-management-isolated-networks-read` + - `cpe-management-isolated-networks-write` + - `cpe-management-isolated-networks-primary-read` + - `cpe-management-isolated-networks-primary-write` + - `cpe-management-isolated-networks-auxiliary-read` + - `cpe-management-isolated-networks-auxiliary-write` + value: + - *base-network + - id: *network-id2 + description: *network-description2 + accessDetail: *network-access-detail2 + expiration: *network-expiration2 + createdAt: *network-created-at2 + createdBy: *network-created-by2 + modifiedAt: *network-modified-at2 + modifiedBy: *network-modified-by2 + version: *network-version2 + + NetworkListWithDevices: + summary: Network List with Devices + description: | + Output with the following scope(s): + - **any of** + - `cpe-management-isolated-networks-read` + - `cpe-management-isolated-networks-write` + - `cpe-management-isolated-networks-primary-read` + - `cpe-management-isolated-networks-primary-write` + - `cpe-management-isolated-networks-auxiliary-read` + - `cpe-management-isolated-networks-auxiliary-write` + - **any of** + - `cpe-management-devices-read` + - `cpe-management-devices-write` + - `cpe-management-devices-hardware-address-read` + value: *network-list + + BaseRebootRequest: + summary: Reboot Request with Default Device + description: | + Output with the following scope(s): + - **any of** + - `cpe-management-reboot-requests-read` + - `cpe-management-reboot-requests-write` + value: &base-reboot-request + id: *reboot-id + message: *reboot-message + atTime: *reboot-at-time + createdAt: *reboot-created + createdBy: *reboot-created-by + modifiedAt: *reboot-modified + modifiedBy: *reboot-modified-by + + RebootRequestWithDevices: + summary: Reboot Request + description: | + Output with the following scope(s): + - **any of** + - `cpe-management-reboot-requests-read` + - `cpe-management-reboot-requests-write` + - **any of** + - `cpe-management-devices-read` + - `cpe-management-devices-write` + - `cpe-management-devices-hardware-address-read` + value: *reboot-request + + RebootRequestUpdate: + summary: Reboot Request Update + description: | + Post with the following scope(s): + - **any of** + - `cpe-management-reboot-requests-write` + value: *reboot-request-update + + BaseRebootRequestCreate: + summary: Create Reboot Request for Default Device + description: | + Post with the following scope(s): + - **any of** + - `cpe-management-reboot-requests-write` + value: &reboot-request-update + message: *reboot-message + atTime: *reboot-at-time + + RebootRequestCreateWithDevices: + summary: Create Reboot Request for Devices + description: | + Post with the following scope(s): + - **any of** + - `cpe-management-reboot-requests-write` + - `cpe-management-devices-write` + value: *reboot-create + + BaseRebootRequestList: + summary: Reboot Request List with Default Device + description: | + Output with the following scope(s): + - **any of** + - `cpe-management-reboot-requests-read` + - `cpe-management-reboot-requests-write` + value: + - *base-reboot-request + - id: *reboot-id2 + message: *reboot-message2 + atTime: *reboot-at-time2 + createdAt: *reboot-created-at2 + createdBy: *reboot-created-by2 + modifiedAt: *reboot-modified-at2 + modifiedBy: *reboot-modified-by2 + + RebootRequestListWithDevices: + summary: Reboot Request List + description: | + Output with the following scope(s): + - **any of** + - `cpe-management-reboot-requests-read` + - `cpe-management-reboot-requests-write` + - **any of** + - `cpe-management-devices-read` + - `cpe-management-devices-write` + - `cpe-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" From 08c8a662deb76e2ecdf69c6bb3c278b5c752574a Mon Sep 17 00:00:00 2001 From: Christopher Aubut <89488056+caubut-charter@users.noreply.github.com> Date: Wed, 26 Jun 2024 21:05:52 +0000 Subject: [PATCH 02/30] Update code/API_definitions/network_access_management.yaml Co-authored-by: Herbert Damker <52109189+hdamker@users.noreply.github.com> --- code/API_definitions/network_access_management.yaml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/code/API_definitions/network_access_management.yaml b/code/API_definitions/network_access_management.yaml index c169f7f..d97ee91 100644 --- a/code/API_definitions/network_access_management.yaml +++ b/code/API_definitions/network_access_management.yaml @@ -2,7 +2,8 @@ openapi: 3.0.3 info: title: CPE Management API - version: 0.0.1 + version: wip + 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. From c0130f6defd267fc0e261df074fbebb1de278d09 Mon Sep 17 00:00:00 2001 From: Christopher Aubut <89488056+caubut-charter@users.noreply.github.com> Date: Wed, 26 Jun 2024 21:06:21 +0000 Subject: [PATCH 03/30] Update code/API_definitions/network_access_management.yaml Co-authored-by: Ben Hepworth <125334035+benhepworth@users.noreply.github.com> --- code/API_definitions/network_access_management.yaml | 1 - 1 file changed, 1 deletion(-) diff --git a/code/API_definitions/network_access_management.yaml b/code/API_definitions/network_access_management.yaml index d97ee91..cdd2ade 100644 --- a/code/API_definitions/network_access_management.yaml +++ b/code/API_definitions/network_access_management.yaml @@ -277,7 +277,6 @@ paths: get: tags: - Service Sites - - Isolated Networks summary: Get all networks at a service site operationId: getNetworksByServiceSite description: | From 8e04d6db218a8c6fbc799a6cfb6cd67b63a10b0c Mon Sep 17 00:00:00 2001 From: Christopher Aubut <89488056+caubut-charter@users.noreply.github.com> Date: Wed, 26 Jun 2024 21:07:03 +0000 Subject: [PATCH 04/30] Update code/API_definitions/network_access_management.yaml Co-authored-by: Ben Hepworth <125334035+benhepworth@users.noreply.github.com> --- code/API_definitions/network_access_management.yaml | 2 -- 1 file changed, 2 deletions(-) diff --git a/code/API_definitions/network_access_management.yaml b/code/API_definitions/network_access_management.yaml index cdd2ade..fad75e6 100644 --- a/code/API_definitions/network_access_management.yaml +++ b/code/API_definitions/network_access_management.yaml @@ -826,8 +826,6 @@ paths: $ref: "#/components/responses/Generic503" /isolated-networks/{netId}/devices: - parameters: - - $ref: "#/components/parameters/netId" get: tags: - Devices From 39e3291f59eed822f002273d853ac143e226a022 Mon Sep 17 00:00:00 2001 From: Christopher Aubut <89488056+caubut-charter@users.noreply.github.com> Date: Wed, 26 Jun 2024 21:07:23 +0000 Subject: [PATCH 05/30] Update code/API_definitions/network_access_management.yaml Co-authored-by: Ben Hepworth <125334035+benhepworth@users.noreply.github.com> --- code/API_definitions/network_access_management.yaml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/code/API_definitions/network_access_management.yaml b/code/API_definitions/network_access_management.yaml index fad75e6..1bb2328 100644 --- a/code/API_definitions/network_access_management.yaml +++ b/code/API_definitions/network_access_management.yaml @@ -901,6 +901,8 @@ paths: - `cpe-management-isolated-networks-primary-write` - `cpe-management-isolated-networks-auxiliary-read` - `cpe-management-isolated-networks-auxiliary-write` + parameters: + - $ref: "#/components/parameters/netId" requestBody: required: true content: From d79c7ee1f3c9d778406339fc25b20712b01529b9 Mon Sep 17 00:00:00 2001 From: Christopher Aubut <89488056+caubut-charter@users.noreply.github.com> Date: Wed, 26 Jun 2024 21:10:08 +0000 Subject: [PATCH 06/30] Update code/API_definitions/network_access_management.yaml Co-authored-by: Ben Hepworth <125334035+benhepworth@users.noreply.github.com> --- code/API_definitions/network_access_management.yaml | 2 -- 1 file changed, 2 deletions(-) diff --git a/code/API_definitions/network_access_management.yaml b/code/API_definitions/network_access_management.yaml index 1bb2328..a537d74 100644 --- a/code/API_definitions/network_access_management.yaml +++ b/code/API_definitions/network_access_management.yaml @@ -385,8 +385,6 @@ paths: $ref: "#/components/responses/Generic503" /devices/{deviceId}: - parameters: - - $ref: "#/components/parameters/deviceId" get: tags: - Devices From b03d3fc4908ff2e83a324fb495c805fadbf7c8dc Mon Sep 17 00:00:00 2001 From: Christopher Aubut <89488056+caubut-charter@users.noreply.github.com> Date: Wed, 26 Jun 2024 21:24:15 +0000 Subject: [PATCH 07/30] Apply suggestions from code review Co-authored-by: Ben Hepworth <125334035+benhepworth@users.noreply.github.com> --- code/API_definitions/network_access_management.yaml | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/code/API_definitions/network_access_management.yaml b/code/API_definitions/network_access_management.yaml index a537d74..fcbd263 100644 --- a/code/API_definitions/network_access_management.yaml +++ b/code/API_definitions/network_access_management.yaml @@ -213,7 +213,6 @@ paths: /service-sites/{siteId}/devices: get: tags: - - Service Sites - Devices summary: Get all devices at the service site security: @@ -409,6 +408,8 @@ paths: - `cpe-management-isolated-networks-primary-write` - `cpe-management-isolated-networks-auxiliary-read` - `cpe-management-isolated-networks-auxiliary-write` + parameters: + - $ref: "#/components/parameters/deviceId" responses: "200": description: Contains information about the device @@ -449,8 +450,6 @@ paths: $ref: "#/components/responses/Generic503" /devices/{deviceId}/isolated-networks: - parameters: - - $ref: "#/components/parameters/deviceId" get: tags: - Devices @@ -472,6 +471,8 @@ paths: - `cpe-management-isolated-networks-primary-write` - `cpe-management-isolated-networks-auxiliary-read` - `cpe-management-isolated-networks-auxiliary-write` + parameters: + - $ref: "#/components/parameters/deviceId" responses: "200": description: Contains information about networks configured on the device @@ -518,6 +519,8 @@ paths: - `cpe-management-isolated-networks-primary-write` - `cpe-management-isolated-networks-auxiliary-read` - `cpe-management-isolated-networks-auxiliary-write` + parameters: + - $ref: "#/components/parameters/deviceId" requestBody: required: true content: @@ -850,6 +853,8 @@ paths: - **any of** - `cpe-management-service-sites-read` - `cpe-management-service-sites-location-read` + parameters: + - $ref: "#/components/parameters/netId" responses: "200": description: Contains information about devices configured with the network From 606094c90c73f1e18d59030fcab88e370a8eac1a Mon Sep 17 00:00:00 2001 From: Christopher Aubut <89488056+caubut-charter@users.noreply.github.com> Date: Wed, 26 Jun 2024 21:31:39 +0000 Subject: [PATCH 08/30] Update code/API_definitions/network_access_management.yaml Co-authored-by: Ben Hepworth <125334035+benhepworth@users.noreply.github.com> --- code/API_definitions/network_access_management.yaml | 1 - 1 file changed, 1 deletion(-) diff --git a/code/API_definitions/network_access_management.yaml b/code/API_definitions/network_access_management.yaml index fcbd263..dcc39ab 100644 --- a/code/API_definitions/network_access_management.yaml +++ b/code/API_definitions/network_access_management.yaml @@ -501,7 +501,6 @@ paths: patch: tags: - Devices - - Isolated Networks summary: Bulk insert, remove or replace many networks from the configuration of a device operationId: patchDeviceWithNetworks description: | From 1f237751781aa516cc391754afe0d71181881107 Mon Sep 17 00:00:00 2001 From: Christopher Aubut <89488056+caubut-charter@users.noreply.github.com> Date: Wed, 26 Jun 2024 21:33:09 +0000 Subject: [PATCH 09/30] Update code/API_definitions/network_access_management.yaml --- code/API_definitions/network_access_management.yaml | 1 - 1 file changed, 1 deletion(-) diff --git a/code/API_definitions/network_access_management.yaml b/code/API_definitions/network_access_management.yaml index dcc39ab..9b4e850 100644 --- a/code/API_definitions/network_access_management.yaml +++ b/code/API_definitions/network_access_management.yaml @@ -829,7 +829,6 @@ paths: get: tags: - Devices - - Isolated Networks summary: Get all devices configured with a network operationId: getDevicesByNetwork description: | From a377ecc98ddfff71a57f869a9d063aa59a4367a5 Mon Sep 17 00:00:00 2001 From: Christopher Aubut <89488056+caubut-charter@users.noreply.github.com> Date: Wed, 26 Jun 2024 21:34:25 +0000 Subject: [PATCH 10/30] Update code/API_definitions/network_access_management.yaml --- code/API_definitions/network_access_management.yaml | 1 - 1 file changed, 1 deletion(-) diff --git a/code/API_definitions/network_access_management.yaml b/code/API_definitions/network_access_management.yaml index 9b4e850..4c64101 100644 --- a/code/API_definitions/network_access_management.yaml +++ b/code/API_definitions/network_access_management.yaml @@ -887,7 +887,6 @@ paths: patch: tags: - Devices - - Isolated Networks summary: Bulk insert, remove, or replace a network from the configuration of many devices operationId: patchDevicesWithNetwork description: | From 95b5a28d88f5dace4f6634ed4b9bfb6f52adbe16 Mon Sep 17 00:00:00 2001 From: Christopher Aubut <89488056+caubut-charter@users.noreply.github.com> Date: Wed, 26 Jun 2024 21:35:07 +0000 Subject: [PATCH 11/30] Update code/API_definitions/network_access_management.yaml --- code/API_definitions/network_access_management.yaml | 1 - 1 file changed, 1 deletion(-) diff --git a/code/API_definitions/network_access_management.yaml b/code/API_definitions/network_access_management.yaml index 4c64101..774c687 100644 --- a/code/API_definitions/network_access_management.yaml +++ b/code/API_definitions/network_access_management.yaml @@ -452,7 +452,6 @@ paths: /devices/{deviceId}/isolated-networks: get: tags: - - Devices - Isolated Networks summary: Get all networks configured on a device operationId: getNetworksByDevice From a153d8952d12cfb72acd0237ccbaecfef729957a Mon Sep 17 00:00:00 2001 From: Christopher Aubut Date: Fri, 5 Jul 2024 11:58:18 -0600 Subject: [PATCH 12/30] chore: updates info object and bumps openapi@3.0.3 -> 3.1.0 --- code/API_definitions/README.MD | 1 - code/API_definitions/network_access_management.yaml | 13 ++++++------- 2 files changed, 6 insertions(+), 8 deletions(-) delete mode 100644 code/API_definitions/README.MD 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 index 774c687..42f61a1 100644 --- a/code/API_definitions/network_access_management.yaml +++ b/code/API_definitions/network_access_management.yaml @@ -1,9 +1,7 @@ -openapi: 3.0.3 +openapi: 3.1.0 info: - title: CPE Management API - version: wip - + 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. @@ -79,12 +77,13 @@ info: ### 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 + url: https://www.apache.org/licenses/LICENSE-2.0.html + x-camara-commonalities: 0.4.0 contact: - email: project-manager@cablelabs.com + email: sp-nam@lists.camaraproject.org tags: - name: Service Sites From 60d81fee632e4905ef4990beb8fea41e37d80297 Mon Sep 17 00:00:00 2001 From: Christopher Aubut Date: Fri, 5 Jul 2024 12:04:00 -0600 Subject: [PATCH 13/30] chore: updates server object --- .../network_access_management.yaml | 17 +++++++---------- 1 file changed, 7 insertions(+), 10 deletions(-) diff --git a/code/API_definitions/network_access_management.yaml b/code/API_definitions/network_access_management.yaml index 42f61a1..67f40c0 100644 --- a/code/API_definitions/network_access_management.yaml +++ b/code/API_definitions/network_access_management.yaml @@ -85,22 +85,19 @@ info: 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: Service Sites - name: Devices - name: Isolated Networks - name: Reboot Requests -servers: - - url: "{apiRoot}/{basePath}" - variables: - apiRoot: - default: http://localhost:5000 - description: API root - basePath: - default: cpe-management/v0 - description: Base path for the CPE Management API - security: - oauth2: [] From f5b708ef7018ca46c0d776639e9e630b58179ce4 Mon Sep 17 00:00:00 2001 From: Christopher Aubut Date: Fri, 5 Jul 2024 12:05:51 -0600 Subject: [PATCH 14/30] fix: reverts openapi to 3.0.3 --- code/API_definitions/network_access_management.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/code/API_definitions/network_access_management.yaml b/code/API_definitions/network_access_management.yaml index 67f40c0..7885984 100644 --- a/code/API_definitions/network_access_management.yaml +++ b/code/API_definitions/network_access_management.yaml @@ -1,4 +1,4 @@ -openapi: 3.1.0 +openapi: 3.0.3 info: title: Home Devices - Network Access Management From 2492bf1a80ea917907e7d4095689d11739f97c33 Mon Sep 17 00:00:00 2001 From: Christopher Aubut Date: Fri, 5 Jul 2024 13:05:06 -0600 Subject: [PATCH 15/30] style: linewraps text blocks to 120 chars --- .../network_access_management.yaml | 188 +++++++++++++----- 1 file changed, 137 insertions(+), 51 deletions(-) diff --git a/code/API_definitions/network_access_management.yaml b/code/API_definitions/network_access_management.yaml index 7885984..2194441 100644 --- a/code/API_definitions/network_access_management.yaml +++ b/code/API_definitions/network_access_management.yaml @@ -3,44 +3,81 @@ 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. + 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: + 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 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 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. + - **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. + - **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. + - **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. OAuth 2.0 is used for authorizing an identity (resource holder) and scopes are used for role-based authorization. + This API allows API clients to manage isolated networks and reboot network access devices. OAuth 2.0 is used for + authorizing an identity (resource holder) and scopes are used for role-based authorization. ## Authorization - Authorization of API clients SHOULD be performed with OAuth 2.0 using the authorization code grant type such that service owners delegate access to their resources exposed by this API to the API client. PKCE MUST be used when the API client secret cannot be secured (e.g., mobile application or single page application without a secure back-end). This API MAY also be used with the client credentials grant type, though such a use case only makes sense for first-party network operator API clients or when the service owner operates their own API client (client ID is bound to the service owner's identity). + Authorization of API clients SHOULD be performed with OAuth 2.0 using the authorization code grant type such that + service owners delegate access to their resources exposed by this API to the API client. PKCE MUST be used when the + API client secret cannot be secured (e.g., mobile application or single page application without a secure back-end). + This API MAY also be used with the client credentials grant type, though such a use case only makes sense for + first-party network operator API clients or when the service owner operates their own API client (client ID is bound + to the service owner's identity). ### Scopes - OAuth 2.0 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. + OAuth 2.0 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. + - 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 |-------|-------------|--------- @@ -62,21 +99,37 @@ info: OAuth 2.0 claims are not used by this API to allow for the use of JSON Web Encryption (JWE) access tokens. ## 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.). + 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 OAuth 2.0 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. + When an identity for OAuth 2.0 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. + 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. + 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 @@ -114,7 +167,8 @@ paths: - cpe-management-devices-read operationId: getServiceSites description: | - Returns all service sites. Scopes impact the output of this endpoint. See the examples for various permutations. + Returns all service sites. Scopes impact the output of this endpoint. See the examples for various + permutations. **Required Scopes:** - **any of** @@ -162,7 +216,8 @@ paths: - cpe-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. + Returns a service site that matches the given ID. Scopes impact the output of this endpoint. See the examples + for various permutations. **Required Scopes:** - **any of** @@ -216,7 +271,8 @@ paths: - cpe-management-service-sites-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. + 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:** - **any of** @@ -386,7 +442,8 @@ paths: summary: Get a device by ID operationId: getDevice description: | - Returns a device that matches the given ID. Scopes impact the output of this endpoint. See the examples for various permutations. + Returns a device that matches the given ID. Scopes impact the output of this endpoint. See the examples for + various permutations. **Required Scopes:** - **any of** @@ -452,7 +509,8 @@ paths: summary: Get all networks configured on a device 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. + 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:** - **any of** @@ -601,10 +659,13 @@ paths: summary: Create a new network operationId: createNetwork description: | - Creates and returns the new network. Scopes impact the function and output of this endpoint. See the examples for various permutations. + 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`. + 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:** - **any of** @@ -664,7 +725,8 @@ paths: summary: Get a Network by ID operationId: getNetwork description: | - Returns the network that matches the given ID. Scopes impact the output of this endpoint. See the examples for various permutations. + 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:** @@ -724,7 +786,8 @@ paths: summary: Update an existing network 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. + 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:** @@ -784,7 +847,8 @@ paths: summary: Delete a network operationId: deleteNetwork description: | - Deletes the network and removes the configuration from any devices configured with the network that matches the given ID. + Deletes the network and removes the configuration from any devices configured with the network that matches the + given ID. ## With Default Device **Required Scopes:** @@ -827,7 +891,8 @@ paths: summary: Get all devices configured with a network 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. + 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:** - **any of** @@ -929,7 +994,8 @@ paths: summary: Get all Reboot Requests operationId: getRebootRequests description: | - Returns all reboot requests. Scopes impact the output of this endpoint. See the examples for various permutations. + Returns all reboot requests. Scopes impact the output of this endpoint. See the examples for various + permutations. ## With Default Device **Required Scopes:** @@ -975,17 +1041,20 @@ paths: summary: Create a new reboot request 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. + 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`. + 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:** - **any of** - `cpe-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`. + 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:** - `cpe-management-devices-write` @@ -1034,7 +1103,8 @@ paths: summary: Get a Reboot Request by ID 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. + 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:** @@ -1086,7 +1156,9 @@ paths: summary: Update an existing reboot request 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. + 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:** @@ -1185,19 +1257,32 @@ components: tokenUrl: &token-url "https://api.example.com/oauth2/token" refreshUrl: &token-refresh-url "https://api.example.com/refresh" scopes: &scopes - cpe-management-service-sites-read: List a service owner's service sites - cpe-management-service-sites-location-read: Read a service site's physical location - cpe-management-devices-read: List a service owner's devices - cpe-management-devices-hardware-address-read: Read a service owner's device's hardware address - cpe-management-devices-write: Modify which networks are configured on a service owner's devices - cpe-management-isolated-networks-read: List a service owner's isolated networks created by the calling API client - cpe-management-isolated-networks-write: Create or modify a service owner's isolated networks created by the calling API client - cpe-management-isolated-networks-primary-read: Access information about a service owner's primary isolated network - cpe-management-isolated-networks-primary-write: Modify a service owner's primary isolated network - cpe-management-isolated-networks-auxiliary-read: List service owner's auxiliary isolated networks - cpe-management-isolated-networks-auxiliary-write: Create or modify a service owner's auxiliary isolated networks - cpe-management-reboot-requests-read: List a service owner's reboot requests created by the calling API client - cpe-management-reboot-requests-write: Create or modify a service owner's reboot request created by the calling API client + cpe-management-service-sites-read: | + List a service owner's service sites + cpe-management-service-sites-location-read: | + Read a service site's physical location + cpe-management-devices-read: | + List a service owner's devices + cpe-management-devices-hardware-address-read: | + Read a service owner's device's hardware address + cpe-management-devices-write: | + Modify which networks are configured on a service owner's devices + cpe-management-isolated-networks-read: | + List a service owner's isolated networks created by the calling API client + cpe-management-isolated-networks-write: | + Create or modify a service owner's isolated networks created by the calling API client + cpe-management-isolated-networks-primary-read: | + Access information about a service owner's primary isolated network + cpe-management-isolated-networks-primary-write: | + Modify a service owner's primary isolated network + cpe-management-isolated-networks-auxiliary-read: | + List service owner's auxiliary isolated networks + cpe-management-isolated-networks-auxiliary-write: | + Create or modify a service owner's auxiliary isolated networks + cpe-management-reboot-requests-read: | + List a service owner's reboot requests created by the calling API client + cpe-management-reboot-requests-write: | + Create or modify a service owner's reboot request created by the calling API client clientCredentials: tokenUrl: *token-url refreshUrl: *token-refresh-url @@ -2059,7 +2144,8 @@ components: 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. + 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 From 24d065f38d0fac6c86713cbd94949b37a6b45ced Mon Sep 17 00:00:00 2001 From: Christopher Aubut Date: Fri, 5 Jul 2024 13:36:43 -0600 Subject: [PATCH 16/30] chore: updates tags to commonalities spec --- .../network_access_management.yaml | 60 +++++++++++-------- 1 file changed, 35 insertions(+), 25 deletions(-) diff --git a/code/API_definitions/network_access_management.yaml b/code/API_definitions/network_access_management.yaml index 2194441..cb947e1 100644 --- a/code/API_definitions/network_access_management.yaml +++ b/code/API_definitions/network_access_management.yaml @@ -146,10 +146,20 @@ servers: description: API root, defined by the service provider, e.g. `api.example.com` or `api.example.com/somepath` tags: - - name: Service Sites - - name: Devices - - name: Isolated Networks - - name: Reboot Requests + - 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 security: - oauth2: [] @@ -158,7 +168,7 @@ paths: /service-sites: get: tags: - - Service Sites + - Retrieve Service Site summary: Get all service sites security: - oauth2: @@ -209,7 +219,7 @@ paths: /service-sites/{siteId}: get: tags: - - Service Sites + - Retrieve Service Site summary: Get a service site by ID security: - oauth2: @@ -264,8 +274,8 @@ paths: /service-sites/{siteId}/devices: get: tags: - - Devices - summary: Get all devices at the service site + - Retrieve Device + summary: Get all devices at a service site security: - oauth2: - cpe-management-service-sites-read @@ -327,7 +337,7 @@ paths: /service-sites/{siteId}/isolated-networks: get: tags: - - Service Sites + - Retrieve Service Site summary: Get all networks at a service site operationId: getNetworksByServiceSite description: | @@ -378,7 +388,7 @@ paths: /devices: get: tags: - - Devices + - Retrieve Device summary: Get all devices operationId: getDevices description: | @@ -438,7 +448,7 @@ paths: /devices/{deviceId}: get: tags: - - Devices + - Retrieve Device summary: Get a device by ID operationId: getDevice description: | @@ -505,7 +515,7 @@ paths: /devices/{deviceId}/isolated-networks: get: tags: - - Isolated Networks + - Retrieve Isolated Network summary: Get all networks configured on a device operationId: getNetworksByDevice description: | @@ -553,7 +563,7 @@ paths: patch: tags: - - Devices + - Device Configure summary: Bulk insert, remove or replace many networks from the configuration of a device operationId: patchDeviceWithNetworks description: | @@ -600,7 +610,7 @@ paths: /isolated-networks: get: tags: - - Isolated Networks + - Retrieve Isolated Network summary: Get all Networks operationId: getNetworks description: | @@ -655,7 +665,7 @@ paths: post: tags: - - Isolated Networks + - Configure and Apply Isolated Network summary: Create a new network operationId: createNetwork description: | @@ -721,7 +731,7 @@ paths: /isolated-networks/{netId}: get: tags: - - Isolated Networks + - Retrieve Isolated Network summary: Get a Network by ID operationId: getNetwork description: | @@ -782,7 +792,7 @@ paths: patch: tags: - - Isolated Networks + - Configure and Apply Isolated Network summary: Update an existing network operationId: updateNetwork description: | @@ -843,7 +853,7 @@ paths: delete: tags: - - Isolated Networks + - Configure and Apply Isolated Network summary: Delete a network operationId: deleteNetwork description: | @@ -887,7 +897,7 @@ paths: /isolated-networks/{netId}/devices: get: tags: - - Devices + - Retrieve Device summary: Get all devices configured with a network operationId: getDevicesByNetwork description: | @@ -946,7 +956,7 @@ paths: patch: tags: - - Devices + - Device Configure summary: Bulk insert, remove, or replace a network from the configuration of many devices operationId: patchDevicesWithNetwork description: | @@ -990,7 +1000,7 @@ paths: /reboot-requests: get: tags: - - Reboot Requests + - Retrieve Reboot Request summary: Get all Reboot Requests operationId: getRebootRequests description: | @@ -1037,7 +1047,7 @@ paths: post: tags: - - Reboot Requests + - Configure Reboot Request summary: Create a new reboot request operationId: createRebootRequest description: | @@ -1099,7 +1109,7 @@ paths: /reboot-requests/{rebootId}: get: tags: - - Reboot Requests + - Retrieve Reboot Request summary: Get a Reboot Request by ID operationId: getRebootRequest description: | @@ -1152,7 +1162,7 @@ paths: patch: tags: - - Reboot Requests + - Configure Reboot Request summary: Update an existing reboot request operationId: updateRebootRequest description: | @@ -1210,7 +1220,7 @@ paths: delete: tags: - - Reboot Requests + - Configure Reboot Request summary: Delete a reboot request operationId: deleteRebootRequest description: | From cc77ada84bb071fda21b17aed861b590d79efd90 Mon Sep 17 00:00:00 2001 From: Christopher Aubut Date: Fri, 5 Jul 2024 14:01:19 -0600 Subject: [PATCH 17/30] chore: updates datetime to commonalities spec --- .../network_access_management.yaml | 212 ++++++++++-------- 1 file changed, 114 insertions(+), 98 deletions(-) diff --git a/code/API_definitions/network_access_management.yaml b/code/API_definitions/network_access_management.yaml index cb947e1..f8270fa 100644 --- a/code/API_definitions/network_access_management.yaml +++ b/code/API_definitions/network_access_management.yaml @@ -55,28 +55,28 @@ info: Authorization of API clients SHOULD be performed with OAuth 2.0 using the authorization code grant type such that service owners delegate access to their resources exposed by this API to the API client. PKCE MUST be used when the API client secret cannot be secured (e.g., mobile application or single page application without a secure back-end). - This API MAY also be used with the client credentials grant type, though such a use case only makes sense for - first-party network operator API clients or when the service owner operates their own API client (client ID is bound + This API MAY also be used with the client credentials grant type, though such a use case only makes sense for + first-party network operator API clients or when the service owner operates their own API client (client ID is bound to the service owner's identity). ### Scopes - OAuth 2.0 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 + OAuth 2.0 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. + - 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 + - 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 + - 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 @@ -99,21 +99,21 @@ info: OAuth 2.0 claims are not used by this API to allow for the use of JSON Web Encryption (JWE) access tokens. ## 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 + 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 + 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 OAuth 2.0 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 + When an identity for OAuth 2.0 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 @@ -125,10 +125,10 @@ info: ### 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 + 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: @@ -177,7 +177,7 @@ paths: - cpe-management-devices-read operationId: getServiceSites description: | - Returns all service sites. Scopes impact the output of this endpoint. See the examples for various + Returns all service sites. Scopes impact the output of this endpoint. See the examples for various permutations. **Required Scopes:** @@ -281,7 +281,7 @@ paths: - cpe-management-service-sites-read operationId: getDevicesByServiceSite description: | - Returns all devices at a service site that matches the given ID. Scopes impact the output of this endpoint. + 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:** @@ -452,7 +452,7 @@ paths: summary: Get a device by ID operationId: getDevice description: | - Returns a device that matches the given ID. Scopes impact the output of this endpoint. See the examples for + Returns a device that matches the given ID. Scopes impact the output of this endpoint. See the examples for various permutations. **Required Scopes:** @@ -519,7 +519,7 @@ paths: summary: Get all networks configured on a device operationId: getNetworksByDevice description: | - Returns all networks configured on a device that matches the given ID. Scopes impact the output of this + 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:** @@ -673,8 +673,8 @@ paths: 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 + 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:** @@ -735,7 +735,7 @@ paths: summary: Get a Network by ID operationId: getNetwork description: | - Returns the network that matches the given ID. Scopes impact the output of this endpoint. See the examples for + Returns the network that matches the given ID. Scopes impact the output of this endpoint. See the examples for various permutations. ## With Default Device @@ -901,7 +901,7 @@ paths: summary: Get all devices configured with a network operationId: getDevicesByNetwork description: | - Returns all devices configured with a network that matches the given ID. Scopes impact the output of this + 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:** @@ -1004,7 +1004,7 @@ paths: summary: Get all Reboot Requests operationId: getRebootRequests description: | - Returns all reboot requests. Scopes impact the output of this endpoint. See the examples for various + Returns all reboot requests. Scopes impact the output of this endpoint. See the examples for various permutations. ## With Default Device @@ -1051,11 +1051,11 @@ paths: summary: Create a new reboot request operationId: createRebootRequest description: | - Creates and returns the new reboot request. Scopes impact the function and output of this endpoint. See the + 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 + 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:** @@ -1063,7 +1063,7 @@ paths: - `cpe-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 + 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:** @@ -1113,7 +1113,7 @@ paths: summary: Get a Reboot Request by ID operationId: getRebootRequest description: | - Returns the reboot request that matches the given ID. Scopes impact the output of this endpoint. See the + 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 @@ -1166,8 +1166,8 @@ paths: summary: Update an existing reboot request 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 + 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 @@ -1332,6 +1332,15 @@ components: 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 @@ -1923,14 +1932,15 @@ components: - $ref: "#/components/schemas/AccessDetail" example: *wifi-access-detail expiration: - type: string - format: date-time - description: The expiration date and time of the network - example: &network-expiration "1970-01-03T00:00:00.000Z" + $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: *network-expiration + expiration: *date-time NetworkCreate: allOf: @@ -1949,7 +1959,7 @@ components: example: &network-create description: *network-description accessDetail: *wifi-access-detail - expiration: *network-expiration + expiration: *date-time devices: *network-device-intersection-create-list Network: @@ -1967,20 +1977,22 @@ components: example: - *network-device-intersection-create-list createdAt: - type: string - format: date-time - description: The creation date and time of the network - example: &network-created "1970-01-01T00:00:00.000Z" + $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: - type: string - format: date-time - description: The last update date and time of the network - example: &network-modified "1970-01-02T00:00:00.000Z" + $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 @@ -1995,11 +2007,11 @@ components: id: *network-id description: *network-description accessDetail: *wifi-access-detail - expiration: *network-expiration + expiration: *date-time devices: *network-device-intersection-list - createdAt: *network-created + createdAt: *date-time createdBy: *network-created-by - modifiedAt: *network-modified + modifiedAt: *date-time modifiedBy: *network-modified-by version: *network-version @@ -2017,13 +2029,13 @@ components: securityMode: password: "my-other-password" securityModeType: "WPA2-Personal" - expiration: &network-expiration2 "2023-08-25T00:42:17.272Z" + expiration: *date-time devices: &network-device-intersection-list2 - device: *device-id2 role: &network-role2 "auxiliary" - createdAt: &network-created-at2 "2023-08-25T00:42:17.272Z" + createdAt: *date-time createdBy: &network-created-by2 "user-3" - modifiedAt: &network-modified-at2 "2023-08-25T00:42:17.272Z" + modifiedAt: date-time modifiedBy: &network-modified-by2 "user-4" version: &network-version2 "0000FFFF" @@ -2137,13 +2149,15 @@ components: description: A message related to the reboot request example: &reboot-message "reboot to correct performance" atTime: - type: string - format: date-time - description: The date and time to reboot the device. Do not include 'atTime' to request immediate reboot. - example: &reboot-at-time "1970-01-03T00:00:00.000Z" + $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: *reboot-at-time + atTime: *date-time RebootRequestCreate: allOf: @@ -2154,12 +2168,12 @@ components: items: $ref: "#/components/schemas/DeviceId" description: >- - List of devices to reboot. When undefined, the reboot targets the 'default' device (simple use case that + 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: *reboot-at-time + atTime: *date-time devices: *device-id-list RebootRequest: @@ -2169,20 +2183,22 @@ components: id: $ref: "#/components/schemas/RebootId" createdAt: - type: string - format: date-time - description: The creation date and time of the reboot request - example: &reboot-created "1970-01-01T00:00:00.000Z" + $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: - type: string - format: date-time - description: The last update date and time of the reboot request - example: &reboot-modified "1970-01-02T00:00:00.000Z" + $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 @@ -2193,11 +2209,11 @@ components: example: &reboot-request id: *reboot-id message: *reboot-message - atTime: *reboot-at-time + atTime: *date-time devices: *device-id-list - createdAt: *reboot-created + createdAt: *date-time createdBy: *reboot-created-by - modifiedAt: *reboot-modified + modifiedAt: *date-time modifiedBy: *reboot-modified-by RebootRequestList: @@ -2208,13 +2224,13 @@ components: - *reboot-request - id: &reboot-id2 "reboot-2" message: &reboot-message2 "my second reboot request" - atTime: &reboot-at-time2 "2023-08-25T00:42:17.272Z" + atTime: *date-time devices: &reboot-devices2 - "device-3" - "device-4" - createdAt: &reboot-created-at2 "2023-08-25T00:42:17.272Z" + createdAt: *date-time createdBy: &reboot-created-by2 "user-3" - modifiedAt: &reboot-modified-at2 "2023-08-25T00:42:17.272Z" + modifiedAt: *date-time modifiedBy: &reboot-modified-by2 "user-4" ErrorInfo: @@ -2620,10 +2636,10 @@ components: id: *network-id description: *network-description accessDetail: *wifi-access-detail - expiration: *network-expiration - createdAt: *network-created + expiration: *date-time + createdAt: *date-time createdBy: *network-created-by - modifiedAt: *network-modified + modifiedAt: *date-time modifiedBy: *network-modified-by version: *network-version @@ -2665,7 +2681,7 @@ components: value: description: *network-description accessDetail: *wifi-access-detail - expiration: *network-expiration + expiration: *date-time NetworkCreateWithDevices: summary: Create Network on Devices @@ -2694,10 +2710,10 @@ components: - id: *network-id2 description: *network-description2 accessDetail: *network-access-detail2 - expiration: *network-expiration2 - createdAt: *network-created-at2 - createdBy: *network-created-by2 - modifiedAt: *network-modified-at2 + expiration: *date-time + createdAt: *date-time + createdBy: *date-time + modifiedAt: *date-time modifiedBy: *network-modified-by2 version: *network-version2 @@ -2728,10 +2744,10 @@ components: value: &base-reboot-request id: *reboot-id message: *reboot-message - atTime: *reboot-at-time - createdAt: *reboot-created + atTime: *date-time + createdAt: *date-time createdBy: *reboot-created-by - modifiedAt: *reboot-modified + modifiedAt: *date-time modifiedBy: *reboot-modified-by RebootRequestWithDevices: @@ -2763,7 +2779,7 @@ components: - `cpe-management-reboot-requests-write` value: &reboot-request-update message: *reboot-message - atTime: *reboot-at-time + atTime: *date-time RebootRequestCreateWithDevices: summary: Create Reboot Request for Devices @@ -2785,10 +2801,10 @@ components: - *base-reboot-request - id: *reboot-id2 message: *reboot-message2 - atTime: *reboot-at-time2 - createdAt: *reboot-created-at2 + atTime: *date-time + createdAt: *date-time createdBy: *reboot-created-by2 - modifiedAt: *reboot-modified-at2 + modifiedAt: *date-time modifiedBy: *reboot-modified-by2 RebootRequestListWithDevices: From aeae88c2a57135677ca8d918bb8194b370d3c8ce Mon Sep 17 00:00:00 2001 From: Christopher Aubut Date: Fri, 5 Jul 2024 14:35:03 -0600 Subject: [PATCH 18/30] chore: updates discriminators to commonalities spec --- .../network_access_management.yaml | 370 ++++++++++-------- 1 file changed, 200 insertions(+), 170 deletions(-) diff --git a/code/API_definitions/network_access_management.yaml b/code/API_definitions/network_access_management.yaml index f8270fa..86cac42 100644 --- a/code/API_definitions/network_access_management.yaml +++ b/code/API_definitions/network_access_management.yaml @@ -1637,41 +1637,69 @@ components: default: "auxiliary" example: &network-role "primary" - NetworkDeviceIntersectionCreate: + NetworkDeviceRoleConfiguration: + 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-role-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. - oneOf: - - required: ["device", "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", "replace"] - 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 + properties: + intersectionType: + type: string + enum: ["NetworkDeviceRoleConfiguration", "NetworkDeviceReplacement"] + example: &network-device-intersection-type "NetworkDeviceRoleConfiguration" required: - - device + - 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 @@ -1682,27 +1710,28 @@ components: example: &network-device-intersection-create-list - *network-device-intersection-create - &network-device-intersection-create-2 + intersectionType: *network-device-intersection-type device: *device-id2 replace: *network-id2 NetworkDeviceIntersection: allOf: - $ref: "#/components/schemas/NetworkDeviceIntersectionCreate" - 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 + - 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 @@ -1720,14 +1749,14 @@ components: description: "ID of the network." allOf: - $ref: "#/components/schemas/NetworkId" - example: *network-id + - example: *network-id role: description: >- Role of the network. Defaults to "auxiliary" if unspecified. default: "auxiliary" allOf: - $ref: "#/components/schemas/NetworkRole" - example: *network-role + - example: *network-role removable: type: boolean description: >- @@ -1791,8 +1820,8 @@ components: networks: allOf: - $ref: "#/components/schemas/DeviceNetworkIntersectionList" - description: The IDs of networks attached to the device - example: *device-network-intersection-list + - description: The IDs of networks attached to the device + example: *device-network-intersection-list maxAuxiliaryNetworks: type: integer description: >- @@ -1930,13 +1959,14 @@ components: description: The access details for the network allOf: - $ref: "#/components/schemas/AccessDetail" - example: *wifi-access-detail + - example: *wifi-access-detail expiration: - $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). + 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 @@ -1945,75 +1975,75 @@ components: 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 + - 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: - $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: - $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 + - 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: + $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: + $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 @@ -2129,7 +2159,7 @@ components: allOf: - $ref: "#/components/schemas/NetworkIdList" - example: &bulk-network-update-delete - - "wifi-3" + - "wifi-3" replace: description: List of network replacements. allOf: @@ -2162,59 +2192,59 @@ components: 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 + - 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: - $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: - $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 + - properties: + id: + $ref: "#/components/schemas/RebootId" + createdAt: + $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: + $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 From 661428ff5991df020cab2a06cc08c8c348b3c999 Mon Sep 17 00:00:00 2001 From: Christopher Aubut Date: Fri, 5 Jul 2024 14:37:54 -0600 Subject: [PATCH 19/30] fix: fixes linting issues --- code/API_definitions/network_access_management.yaml | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/code/API_definitions/network_access_management.yaml b/code/API_definitions/network_access_management.yaml index 86cac42..f35332f 100644 --- a/code/API_definitions/network_access_management.yaml +++ b/code/API_definitions/network_access_management.yaml @@ -1663,7 +1663,7 @@ components: NetworkDeviceReplacement: type: object description: >- - A specific network configuration with an implied network to replace an existing network on specific network + A specific network configuration with an implied network to replace an existing network on specific network access device. properties: device: @@ -1694,10 +1694,10 @@ components: required: - intersectionType discriminator: - propertyName: intersectionType - mappings: - - NetworkDeviceRoleConfiguration: '#/components/schemas/NetworkDeviceRoleConfiguration' - - NetworkDeviceReplacement: '#/components/schemas/NetworkDeviceReplacement' + propertyName: intersectionType + mappings: + - NetworkDeviceRoleConfiguration: '#/components/schemas/NetworkDeviceRoleConfiguration' + - NetworkDeviceReplacement: '#/components/schemas/NetworkDeviceReplacement' example: &network-device-intersection-create intersectionType: *network-device-intersection-type device: *device-id From 5b483b8ea5b4329fa347d04171870e16c3429efd Mon Sep 17 00:00:00 2001 From: Christopher Aubut Date: Fri, 5 Jul 2024 14:45:57 -0600 Subject: [PATCH 20/30] fix: fixes linting issues --- code/API_definitions/network_access_management.yaml | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/code/API_definitions/network_access_management.yaml b/code/API_definitions/network_access_management.yaml index f35332f..82706c0 100644 --- a/code/API_definitions/network_access_management.yaml +++ b/code/API_definitions/network_access_management.yaml @@ -1710,7 +1710,7 @@ components: example: &network-device-intersection-create-list - *network-device-intersection-create - &network-device-intersection-create-2 - intersectionType: *network-device-intersection-type + intersectionType: &network-device-intersection-type-2 "NetworkDeviceReplacement" device: *device-id2 replace: *network-id2 @@ -1729,6 +1729,7 @@ components: required: - device example: &network-device-intersection + intersectionType: *network-device-intersection-type device: *device-id role: *network-role removable: *network-removable @@ -2159,7 +2160,7 @@ components: allOf: - $ref: "#/components/schemas/NetworkIdList" - example: &bulk-network-update-delete - - "wifi-3" + - "wifi-3" replace: description: List of network replacements. allOf: From 9d4d27785b17928822fc8f919df30474da27b687 Mon Sep 17 00:00:00 2001 From: Christopher Aubut Date: Fri, 5 Jul 2024 14:49:19 -0600 Subject: [PATCH 21/30] fix: fixes linting issues --- .../network_access_management.yaml | 57 ++++++++++--------- 1 file changed, 31 insertions(+), 26 deletions(-) diff --git a/code/API_definitions/network_access_management.yaml b/code/API_definitions/network_access_management.yaml index 82706c0..1582a90 100644 --- a/code/API_definitions/network_access_management.yaml +++ b/code/API_definitions/network_access_management.yaml @@ -2008,22 +2008,24 @@ components: example: - *network-device-intersection-create-list createdAt: - $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). + 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: - $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). + 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 @@ -2180,12 +2182,13 @@ components: description: A message related to the reboot request example: &reboot-message "reboot to correct performance" atTime: - $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). + 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 @@ -2214,22 +2217,24 @@ components: id: $ref: "#/components/schemas/RebootId" createdAt: - $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). + 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: - $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). + 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 From 60ca455ad1da91194d5385c17ce59dc364a93d0c Mon Sep 17 00:00:00 2001 From: Christopher Aubut Date: Fri, 5 Jul 2024 15:01:18 -0600 Subject: [PATCH 22/30] fix: fixes linting issues --- .../network_access_management.yaml | 49 +++---------------- 1 file changed, 6 insertions(+), 43 deletions(-) diff --git a/code/API_definitions/network_access_management.yaml b/code/API_definitions/network_access_management.yaml index 1582a90..85886c5 100644 --- a/code/API_definitions/network_access_management.yaml +++ b/code/API_definitions/network_access_management.yaml @@ -1258,45 +1258,9 @@ paths: components: securitySchemes: - oauth2: - type: oauth2 - description: This API uses OAuth 2 with the authorization code grant type flow - flows: - authorizationCode: - authorizationUrl: "https://api.example.com/oauth2/authorize" - tokenUrl: &token-url "https://api.example.com/oauth2/token" - refreshUrl: &token-refresh-url "https://api.example.com/refresh" - scopes: &scopes - cpe-management-service-sites-read: | - List a service owner's service sites - cpe-management-service-sites-location-read: | - Read a service site's physical location - cpe-management-devices-read: | - List a service owner's devices - cpe-management-devices-hardware-address-read: | - Read a service owner's device's hardware address - cpe-management-devices-write: | - Modify which networks are configured on a service owner's devices - cpe-management-isolated-networks-read: | - List a service owner's isolated networks created by the calling API client - cpe-management-isolated-networks-write: | - Create or modify a service owner's isolated networks created by the calling API client - cpe-management-isolated-networks-primary-read: | - Access information about a service owner's primary isolated network - cpe-management-isolated-networks-primary-write: | - Modify a service owner's primary isolated network - cpe-management-isolated-networks-auxiliary-read: | - List service owner's auxiliary isolated networks - cpe-management-isolated-networks-auxiliary-write: | - Create or modify a service owner's auxiliary isolated networks - cpe-management-reboot-requests-read: | - List a service owner's reboot requests created by the calling API client - cpe-management-reboot-requests-write: | - Create or modify a service owner's reboot request created by the calling API client - clientCredentials: - tokenUrl: *token-url - refreshUrl: *token-refresh-url - scopes: *scopes + openId: + type: openIdConnect + openIdConnectUrl: https://example.com/.well-known/openid-configuration parameters: siteId: @@ -1637,7 +1601,7 @@ components: default: "auxiliary" example: &network-role "primary" - NetworkDeviceRoleConfiguration: + NetworkDeviceConfiguration: type: object description: >- A specific network configuration with an implied network to configure on a specific network access device with @@ -1656,7 +1620,7 @@ components: - $ref: "#/components/schemas/NetworkRole" - example: *network-role required: ["device"] - example: &network-device-role-configuration + example: &network-device-configuration device: *device-id role: *network-role @@ -1716,7 +1680,7 @@ components: NetworkDeviceIntersection: allOf: - - $ref: "#/components/schemas/NetworkDeviceIntersectionCreate" + - $ref: "#/components/schemas/NetworkDeviceConfiguration" - description: >- Properties of a specific network configuration with an implied network on a specific network access device. properties: @@ -1729,7 +1693,6 @@ components: required: - device example: &network-device-intersection - intersectionType: *network-device-intersection-type device: *device-id role: *network-role removable: *network-removable From a37d6e8ebe942eb153da5823dba8b6f26ca43c72 Mon Sep 17 00:00:00 2001 From: Christopher Aubut Date: Fri, 5 Jul 2024 15:05:52 -0600 Subject: [PATCH 23/30] fix: fixes linting issues --- code/API_definitions/network_access_management.yaml | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/code/API_definitions/network_access_management.yaml b/code/API_definitions/network_access_management.yaml index 85886c5..cc3a3cf 100644 --- a/code/API_definitions/network_access_management.yaml +++ b/code/API_definitions/network_access_management.yaml @@ -161,9 +161,6 @@ tags: - name: Configure Reboot Requests description: Operations to modify reboot requests -security: - - oauth2: [] - paths: /service-sites: get: @@ -171,7 +168,7 @@ paths: - Retrieve Service Site summary: Get all service sites security: - - oauth2: + - openId: - cpe-management-service-sites-read - cpe-management-service-sites-location-read - cpe-management-devices-read @@ -222,7 +219,7 @@ paths: - Retrieve Service Site summary: Get a service site by ID security: - - oauth2: + - openId: - cpe-management-service-sites-read operationId: getServiceSite description: | @@ -277,7 +274,7 @@ paths: - Retrieve Device summary: Get all devices at a service site security: - - oauth2: + - openId: - cpe-management-service-sites-read operationId: getDevicesByServiceSite description: | @@ -2031,7 +2028,7 @@ components: role: &network-role2 "auxiliary" createdAt: *date-time createdBy: &network-created-by2 "user-3" - modifiedAt: date-time + modifiedAt: *date-time modifiedBy: &network-modified-by2 "user-4" version: &network-version2 "0000FFFF" From fde682121a84f41c6b8b50e974e17a39c4093150 Mon Sep 17 00:00:00 2001 From: Christopher Aubut Date: Fri, 5 Jul 2024 15:16:30 -0600 Subject: [PATCH 24/30] chore: scope names to commonalities spec --- .../network_access_management.yaml | 770 +++++++++--------- 1 file changed, 386 insertions(+), 384 deletions(-) diff --git a/code/API_definitions/network_access_management.yaml b/code/API_definitions/network_access_management.yaml index cc3a3cf..a72e7d6 100644 --- a/code/API_definitions/network_access_management.yaml +++ b/code/API_definitions/network_access_management.yaml @@ -48,19 +48,24 @@ info: - **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. OAuth 2.0 is used for - authorizing an identity (resource holder) and scopes are used for role-based authorization. + This API allows API clients to manage isolated networks and reboot network access devices. - ## Authorization - Authorization of API clients SHOULD be performed with OAuth 2.0 using the authorization code grant type such that - service owners delegate access to their resources exposed by this API to the API client. PKCE MUST be used when the - API client secret cannot be secured (e.g., mobile application or single page application without a secure back-end). - This API MAY also be used with the client credentials grant type, though such a use case only makes sense for - first-party network operator API clients or when the service owner operates their own API client (client ID is bound - to the service owner's identity). + ## 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 - OAuth 2.0 scopes are used to protect the service owner's information and privacy. The general format is + 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 @@ -81,22 +86,19 @@ info: | Scope | Description | Inherits |-------|-------------|--------- - | **cpe-management-service-sites-read** | List a service owner's service sites - | **cpe-management-service-sites-location-read** | Read a service site's physical location | cpe-management-service-sites-read - | **cpe-management-devices-read** | List a service owner's devices - | **cpe-management-devices-hardware-address-read** | Read a service owner's device's hardware address | cpe-management-devices-read - | **cpe-management-devices-write** | Modify which networks are configured on a service owner's devices | cpe-management-devices-read - | **cpe-management-isolated-networks-read** | List a service owner's isolated networks created by the calling API client - | **cpe-management-isolated-networks-write** | Create or modify a service owner's isolated networks created by the calling API client | cpe-management-isolated-networks-read - | **cpe-management-isolated-networks-primary-read** | Access information about a service owner's primary isolated network - | **cpe-management-isolated-networks-primary-write** | Modify a service owner's primary isolated network | cpe-management-isolated-networks-primary-read - | **cpe-management-isolated-networks-auxiliary-read** | List a service owner's auxiliary isolated networks | cpe-management-isolated-networks-read - | **cpe-management-isolated-networks-auxiliary-write** | Create or modify a service owner's auxiliary isolated networks | cpe-management-isolated-networks-auxiliary-read
cpe-management-isolated-networks-write - | **cpe-management-reboot-requests-read** | List a service owner's reboot requests created by the calling API client - | **cpe-management-reboot-requests-write** | Create or modify a service owner's reboot request created by the calling API client | cpe-management-reboot-request-read - - ### Claims - OAuth 2.0 claims are not used by this API to allow for the use of JSON Web Encryption (JWE) access tokens. + | **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 @@ -110,8 +112,8 @@ info: ## Optional Modes ### Default Device - When an identity for OAuth 2.0 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 + 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. @@ -169,9 +171,9 @@ paths: summary: Get all service sites security: - openId: - - cpe-management-service-sites-read - - cpe-management-service-sites-location-read - - cpe-management-devices-read + - network-access-management:service-sites:read + - network-access-management:service-sites.location:read + - network-access-management:devices:read operationId: getServiceSites description: | Returns all service sites. Scopes impact the output of this endpoint. See the examples for various @@ -179,13 +181,13 @@ paths: **Required Scopes:** - **any of** - - `cpe-management-service-sites-read` - - `cpe-management-service-sites-location-read` + - `network-access-management:service-sites:read` + - `network-access-management:service-sites.location:read` **Optional Scopes:** - - `cpe-management-devices-read` - - `cpe-management-devices-write` - - `cpe-management-devices-hardware-address-read` + - `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 @@ -220,7 +222,7 @@ paths: summary: Get a service site by ID security: - openId: - - cpe-management-service-sites-read + - 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 @@ -228,13 +230,13 @@ paths: **Required Scopes:** - **any of** - - `cpe-management-service-sites-read` - - `cpe-management-service-sites-location-read` + - `network-access-management:service-sites:read` + - `network-access-management:service-sites.location:read` **Optional Scopes:** - - `cpe-management-devices-read` - - `cpe-management-devices-write` - - `cpe-management-devices-hardware-address-read` + - `network-access-management:devices:read` + - `network-access-management:devices:write` + - `network-access-management:devices.hardware-address:read` parameters: - $ref: "#/components/parameters/siteId" responses: @@ -275,7 +277,7 @@ paths: summary: Get all devices at a service site security: - openId: - - cpe-management-service-sites-read + - network-access-management:service-sites:read operationId: getDevicesByServiceSite description: | Returns all devices at a service site that matches the given ID. Scopes impact the output of this endpoint. @@ -283,20 +285,20 @@ paths: **Required Scopes:** - **any of** - - `cpe-management-service-sites-read` - - `cpe-management-service-sites-location-read` + - `network-access-management:service-sites:read` + - `network-access-management:service-sites.location:read` - **any of** - - `cpe-management-devices-read` - - `cpe-management-devices-write` - - `cpe-management-devices-hardware-address-read` + - `network-access-management:devices:read` + - `network-access-management:devices:write` + - `network-access-management:devices.hardware-address:read` **Optional Scopes:** - - `cpe-management-isolated-networks-read` - - `cpe-management-isolated-networks-write` - - `cpe-management-isolated-networks-primary-read` - - `cpe-management-isolated-networks-primary-write` - - `cpe-management-isolated-networks-auxiliary-read` - - `cpe-management-isolated-networks-auxiliary-write` + - `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" @@ -342,19 +344,19 @@ paths: **Required Scopes:** - **any of** - - `cpe-management-service-sites-read` - - `cpe-management-service-sites-location-read` + - `network-access-management:service-sites:read` + - `network-access-management:service-sites.location:read` - **any of** - - `cpe-management-devices-read` - - `cpe-management-devices-write` - - `cpe-management-devices-hardware-address-read` + - `network-access-management:devices:read` + - `network-access-management:devices:write` + - `network-access-management:devices.hardware-address:read` - **any of** - - `cpe-management-isolated-networks-read` - - `cpe-management-isolated-networks-write` - - `cpe-management-isolated-networks-primary-read` - - `cpe-management-isolated-networks-primary-write` - - `cpe-management-isolated-networks-auxiliary-read` - - `cpe-management-isolated-networks-auxiliary-write` + - `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: @@ -393,20 +395,20 @@ paths: **Required Scopes:** - **any of** - - `cpe-management-devices-read` - - `cpe-management-devices-write` - - `cpe-management-devices-hardware-address-read` + - `network-access-management:devices:read` + - `network-access-management:devices:write` + - `network-access-management:devices.hardware-address:read` **Optional Scopes:** - **any of** - - `cpe-management-service-sites-read` - - `cpe-management-service-sites-location-read` - - `cpe-management-isolated-networks-read` - - `cpe-management-isolated-networks-write` - - `cpe-management-isolated-networks-primary-read` - - `cpe-management-isolated-networks-primary-write` - - `cpe-management-isolated-networks-auxiliary-read` - - `cpe-management-isolated-networks-auxiliary-write` + - `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 @@ -454,20 +456,20 @@ paths: **Required Scopes:** - **any of** - - `cpe-management-devices-read` - - `cpe-management-devices-write` - - `cpe-management-devices-hardware-address-read` + - `network-access-management:devices:read` + - `network-access-management:devices:write` + - `network-access-management:devices.hardware-address:read` **Optional Scopes:** - **any of** - - `cpe-management-service-sites-read` - - `cpe-management-service-sites-location-read` - - `cpe-management-isolated-networks-read` - - `cpe-management-isolated-networks-write` - - `cpe-management-isolated-networks-primary-read` - - `cpe-management-isolated-networks-primary-write` - - `cpe-management-isolated-networks-auxiliary-read` - - `cpe-management-isolated-networks-auxiliary-write` + - `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: @@ -521,16 +523,16 @@ paths: **Required Scopes:** - **any of** - - `cpe-management-devices-read` - - `cpe-management-devices-write` - - `cpe-management-devices-hardware-address-read` + - `network-access-management:devices:read` + - `network-access-management:devices:write` + - `network-access-management:devices.hardware-address:read` - **any of** - - `cpe-management-isolated-networks-read` - - `cpe-management-isolated-networks-write` - - `cpe-management-isolated-networks-primary-read` - - `cpe-management-isolated-networks-primary-write` - - `cpe-management-isolated-networks-auxiliary-read` - - `cpe-management-isolated-networks-auxiliary-write` + - `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: @@ -570,14 +572,14 @@ paths: is replaced and is no longer assigned to any device, it is considered automatically deleted. **Required Scopes:** - - `cpe-management-devices-write` - - **any of** - - `cpe-management-isolated-networks-read` - - `cpe-management-isolated-networks-write` - - `cpe-management-isolated-networks-primary-read` - - `cpe-management-isolated-networks-primary-write` - - `cpe-management-isolated-networks-auxiliary-read` - - `cpe-management-isolated-networks-auxiliary-write` + - `network-access-management:devices:write` + - **any 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: @@ -616,26 +618,26 @@ paths: ## With Default Device **Required Scopes:** - **any of** - - `cpe-management-isolated-networks-read` - - `cpe-management-isolated-networks-write` - - `cpe-management-isolated-networks-primary-read` - - `cpe-management-isolated-networks-primary-write` - - `cpe-management-isolated-networks-auxiliary-read` - - `cpe-management-isolated-networks-auxiliary-write` + - `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:** - **any of** - - `cpe-management-isolated-networks-read` - - `cpe-management-isolated-networks-write` - - `cpe-management-isolated-networks-primary-read` - - `cpe-management-isolated-networks-primary-write` - - `cpe-management-isolated-networks-auxiliary-read` - - `cpe-management-isolated-networks-auxiliary-write` + - `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` - **any of** - - `cpe-management-devices-read` - - `cpe-management-devices-write` - - `cpe-management-devices-hardware-address-read` + - `network-access-management:devices:read` + - `network-access-management:devices:write` + - `network-access-management:devices.hardware-address:read` responses: "200": @@ -676,19 +678,19 @@ paths: **Required Scopes:** - **any of** - - `cpe-management-isolated-networks-write` - - `cpe-management-isolated-networks-primary-write` - - `cpe-management-isolated-networks-auxiliary-write` + - `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:** - - `cpe-management-devices-write` + - `network-access-management:devices:write` - **any of** - - `cpe-management-isolated-networks-write` - - `cpe-management-isolated-networks-primary-write` - - `cpe-management-isolated-networks-auxiliary-write` + - `network-access-management:isolated-networks:write` + - `network-access-management:isolated-networks.primary:write` + - `network-access-management:isolated-networks.auxiliary:write` requestBody: required: true content: @@ -738,26 +740,26 @@ paths: ## With Default Device **Required Scopes:** - **any of** - - `cpe-management-isolated-networks-read` - - `cpe-management-isolated-networks-write` - - `cpe-management-isolated-networks-primary-read` - - `cpe-management-isolated-networks-primary-write` - - `cpe-management-isolated-networks-auxiliary-read` - - `cpe-management-isolated-networks-auxiliary-write` + - `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:** - **any of** - - `cpe-management-isolated-networks-read` - - `cpe-management-isolated-networks-write` - - `cpe-management-isolated-networks-primary-read` - - `cpe-management-isolated-networks-primary-write` - - `cpe-management-isolated-networks-auxiliary-read` - - `cpe-management-isolated-networks-auxiliary-write` + - `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` - **any of** - - `cpe-management-devices-read` - - `cpe-management-devices-write` - - `cpe-management-devices-hardware-address-read` + - `network-access-management:devices:read` + - `network-access-management:devices:write` + - `network-access-management:devices.hardware-address:read` parameters: - $ref: "#/components/parameters/netId" responses: @@ -799,17 +801,17 @@ paths: ## With Default Device **Required Scopes:** - **any of** - - `cpe-management-isolated-networks-write` - - `cpe-management-isolated-networks-primary-write` - - `cpe-management-isolated-networks-auxiliary-write` + - `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:** - - `cpe-management-devices-write` + - `network-access-management:devices:write` - **any of** - - `cpe-management-isolated-networks-write` - - `cpe-management-isolated-networks-primary-write` - - `cpe-management-isolated-networks-auxiliary-write` + - `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: @@ -860,17 +862,17 @@ paths: ## With Default Device **Required Scopes:** - **any of** - - `cpe-management-isolated-networks-write` - - `cpe-management-isolated-networks-primary-write` - - `cpe-management-isolated-networks-auxiliary-write` + - `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:** - - `cpe-management-devices-write` + - `network-access-management:devices:write` - **any of** - - `cpe-management-isolated-networks-write` - - `cpe-management-isolated-networks-primary-write` - - `cpe-management-isolated-networks-auxiliary-write` + - `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: @@ -903,21 +905,21 @@ paths: **Required Scopes:** - **any of** - - `cpe-management-devices-read` - - `cpe-management-devices-write` - - `cpe-management-devices-hardware-address-read` + - `network-access-management:devices:read` + - `network-access-management:devices:write` + - `network-access-management:devices.hardware-address:read` - **any of** - - `cpe-management-isolated-networks-read` - - `cpe-management-isolated-networks-write` - - `cpe-management-isolated-networks-primary-read` - - `cpe-management-isolated-networks-primary-write` - - `cpe-management-isolated-networks-auxiliary-read` - - `cpe-management-isolated-networks-auxiliary-write` + - `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:** - **any of** - - `cpe-management-service-sites-read` - - `cpe-management-service-sites-location-read` + - `network-access-management:service-sites:read` + - `network-access-management:service-sites.location:read` parameters: - $ref: "#/components/parameters/netId" responses: @@ -960,14 +962,14 @@ paths: Bulk inserts, removes, replaces a network from the configuration of many devices by the given IDs. **Required Scopes:** - - `cpe-management-devices-write` - - **any of** - - `cpe-management-isolated-networks-read` - - `cpe-management-isolated-networks-write` - - `cpe-management-isolated-networks-primary-read` - - `cpe-management-isolated-networks-primary-write` - - `cpe-management-isolated-networks-auxiliary-read` - - `cpe-management-isolated-networks-auxiliary-write` + - `network-access-management:devices:write` + - **any 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: @@ -1007,18 +1009,18 @@ paths: ## With Default Device **Required Scopes:** - **any of** - - `cpe-management-reboot-requests-read` - - `cpe-management-reboot-requests-write` + - `network-access-management:reboot-requests:read` + - `network-access-management:reboot-requests:write` ## Without Default Device **Required Scopes:** - **any of** - - `cpe-management-reboot-requests-read` - - `cpe-management-reboot-requests-write` + - `network-access-management:reboot-requests:read` + - `network-access-management:reboot-requests:write` - **any of** - - `cpe-management-devices-read` - - `cpe-management-devices-write` - - `cpe-management-devices-hardware-address-read` + - `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 @@ -1057,16 +1059,16 @@ paths: **Required Scopes:** - **any of** - - `cpe-management-reboot-requests-write` + - `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:** - - `cpe-management-devices-write` + - `network-access-management:devices:write` - **any of** - - `cpe-management-reboot-requests-write` + - `network-access-management:reboot-requests:write` requestBody: required: true content: @@ -1116,18 +1118,18 @@ paths: ## With Default Device **Required Scopes:** - **any of** - - `cpe-management-reboot-requests-read` - - `cpe-management-reboot-requests-write` + - `network-access-management:reboot-requests:read` + - `network-access-management:reboot-requests:write` ## Without Default Device **Required Scopes:** - **any of** - - `cpe-management-reboot-requests-read` - - `cpe-management-reboot-requests-write` + - `network-access-management:reboot-requests:read` + - `network-access-management:reboot-requests:write` - **any of** - - `cpe-management-devices-read` - - `cpe-management-devices-write` - - `cpe-management-devices-hardware-address-read` + - `network-access-management:devices:read` + - `network-access-management:devices:write` + - `network-access-management:devices.hardware-address:read` parameters: - $ref: "#/components/parameters/rebootId" responses: @@ -1170,13 +1172,13 @@ paths: ## With Default Device **Required Scopes:** - **any of** - - `cpe-management-reboot-requests-write` + - `network-access-management:reboot-requests:write` ## Without Default Device **Required Scopes:** - - `cpe-management-devices-write` + - `network-access-management:devices:write` - **any of** - - `cpe-management-reboot-requests-write` + - `network-access-management:reboot-requests:write` parameters: - $ref: "#/components/parameters/rebootId" requestBody: @@ -1226,13 +1228,13 @@ paths: ## With Default Device **Required Scopes:** - **any of** - - `cpe-management-reboot-requests-write` + - `network-access-management:reboot-requests:write` ## Without Default Device **Required Scopes:** - - `cpe-management-devices-write` + - `network-access-management:devices:write` - **any of** - - `cpe-management-reboot-requests-write` + - `network-access-management:reboot-requests:write` parameters: - $ref: "#/components/parameters/rebootId" responses: @@ -1763,19 +1765,19 @@ components: hardwareAddressType: type: string enum: ["EUI-48"] - example: &device-hardware-address-type "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" + 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 + example: &device.hardware-address + hardwareAddressType: *device.hardware-address-type + value: *device.hardware-address-value serviceSite: $ref: "#/components/schemas/ServiceSiteId" networks: @@ -1798,7 +1800,7 @@ components: id: *device-id name: *device-name description: *device-description - hardwareAddress: *device-hardware-address + hardwareAddress: *device.hardware-address serviceSite: *service-site-id networks: *device-network-intersection-list maxAuxiliaryNetworks: *device-max-networks @@ -1812,7 +1814,7 @@ components: - id: *device-id2 name: &device-name2 "Gateway-2" description: &device-description2 "A second Wi-Fi gateway devices" - hardwareAddress: &device-hardware-address2 + hardwareAddress: &device.hardware-address2 hardwareAddressType: "EUI-48" value: "AB:CD:EF:12:34:56" serviceSite: *service-site-id2 @@ -2251,7 +2253,7 @@ components: summary: Base Service Site description: | Output with the following scope(s): - - `cpe-management-service-sites-read` + - `network-access-management:service-sites:read` value: &base-service-site id: *service-site-id @@ -2259,7 +2261,7 @@ components: summary: Service Site with Location description: | Output with the following scope(s): - - `cpe-management-service-sites-location-read` + - `network-access-management:service-sites.location:read` value: &service-site-with-location id: *service-site-id name: *service-site-name @@ -2270,11 +2272,11 @@ components: summary: Service Site with Devices description: | Output with the following scope(s): - - `cpe-management-service-sites-read` + - `network-access-management:service-sites:read` - **any of** - - `cpe-management-devices-read` - - `cpe-management-devices-write` - - `cpe-management-devices-hardware-address-read` + - `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 @@ -2283,18 +2285,18 @@ components: summary: Service Site with Location and Devices description: | Output with the following scope(s): - - `cpe-management-service-sites-location-read` + - `network-access-management:service-sites.location:read` - **any of** - - `cpe-management-devices-read` - - `cpe-management-devices-write` - - `cpe-management-devices-hardware-address-read` + - `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): - - `cpe-management-service-sites-read` + - `network-access-management:service-sites:read` value: - *base-service-site - id: *service-site-id2 @@ -2303,7 +2305,7 @@ components: summary: Service Site List with Location description: | Output with the following scope(s): - - `cpe-management-service-sites-location-read` + - `network-access-management:service-sites.location:read` value: - *service-site-with-location - id: *service-site-id2 @@ -2315,11 +2317,11 @@ components: summary: Service Site List with Devices description: | Output with the following scope(s): - - `cpe-management-service-sites-read` + - `network-access-management:service-sites:read` - **any of** - - `cpe-management-devices-read` - - `cpe-management-devices-write` - - `cpe-management-devices-hardware-address-read` + - `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 @@ -2329,11 +2331,11 @@ components: summary: Service Site List with Location and Devices description: | Output with the following scope(s): - - `cpe-management-service-sites-location-read` + - `network-access-management:service-sites.location:read` - **any of** - - `cpe-management-devices-read` - - `cpe-management-devices-write` - - `cpe-management-devices-hardware-address-read` + - `network-access-management:devices:read` + - `network-access-management:devices:write` + - `network-access-management:devices.hardware-address:read` value: *service-site-list BaseDevice: @@ -2341,8 +2343,8 @@ components: description: | Output with the following scope(s): - **any of** - - `cpe-management-devices-read` - - `cpe-management-devices-write` + - `network-access-management:devices:read` + - `network-access-management:devices:write` value: &base-device id: *device-id name: *device-name @@ -2352,23 +2354,23 @@ components: summary: Device with Hardware Address description: | Output with the following scope(s): - - `cpe-management-devices-hardware-address-read` - value: &device-with-hardware-address + - `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 + hardwareAddress: *device.hardware-address DeviceWithServiceSite: summary: Device with Service Site description: | Output with the following scope(s): - **any of** - - `cpe-management-devices-read` - - `cpe-management-devices-write` + - `network-access-management:devices:read` + - `network-access-management:devices:write` - **any of** - - `cpe-management-service-sites-read` - - `cpe-management-service-sites-location-read` + - `network-access-management:service-sites:read` + - `network-access-management:service-sites.location:read` value: &device-with-service-site id: *device-id name: *device-name @@ -2380,15 +2382,15 @@ components: description: | Output with the following scope(s): - **any of** - - `cpe-management-devices-read` - - `cpe-management-devices-write` + - `network-access-management:devices:read` + - `network-access-management:devices:write` - **any of** - - `cpe-management-isolated-networks-read` - - `cpe-management-isolated-networks-write` - - `cpe-management-isolated-networks-primary-read` - - `cpe-management-isolated-networks-primary-write` - - `cpe-management-isolated-networks-auxiliary-read` - - `cpe-management-isolated-networks-auxiliary-write` + - `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 @@ -2400,34 +2402,34 @@ components: summary: Device with Hardware Address and Service Site description: | Output with the following scope(s): - - `cpe-management-devices-hardware-address-read` + - `network-access-management:devices.hardware-address:read` - **any of** - - `cpe-management-service-sites-read` - - `cpe-management-service-sites-location-read` - value: &device-with-hardware-address-and-service-site + - `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 + hardwareAddress: *device.hardware-address serviceSite: *service-site-id DeviceWithHardwareAddressAndNetworks: summary: Device with Hardware Address and Networks description: | Output with the following scope(s): - - `cpe-management-devices-hardware-address-read` - - **any of** - - `cpe-management-isolated-networks-read` - - `cpe-management-isolated-networks-write` - - `cpe-management-isolated-networks-primary-read` - - `cpe-management-isolated-networks-primary-write` - - `cpe-management-isolated-networks-auxiliary-read` - - `cpe-management-isolated-networks-auxiliary-write` - value: &device-with-hardware-address-and-networks + - `network-access-management:devices.hardware-address:read` + - **any 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 + hardwareAddress: *device.hardware-address networks: *device-network-intersection-list maxAuxiliaryNetworks: *device-max-networks @@ -2436,18 +2438,18 @@ components: description: | Output with the following scope(s): - **any of** - - `cpe-management-devices-read` - - `cpe-management-devices-write` + - `network-access-management:devices:read` + - `network-access-management:devices:write` - **any of** - - `cpe-management-service-sites-read` - - `cpe-management-service-sites-location-read` + - `network-access-management:service-sites:read` + - `network-access-management:service-sites.location:read` - **any of** - - `cpe-management-isolated-networks-read` - - `cpe-management-isolated-networks-write` - - `cpe-management-isolated-networks-primary-read` - - `cpe-management-isolated-networks-primary-write` - - `cpe-management-isolated-networks-auxiliary-read` - - `cpe-management-isolated-networks-auxiliary-write` + - `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 @@ -2460,17 +2462,17 @@ components: summary: Device with Hardware Address, Service Site, and Networks description: | Output with the following scope(s): - - `cpe-management-devices-hardware-address-read` + - `network-access-management:devices.hardware-address:read` - **any of** - - `cpe-management-service-sites-read` - - `cpe-management-service-sites-location-read` + - `network-access-management:service-sites:read` + - `network-access-management:service-sites.location:read` - **any of** - - `cpe-management-isolated-networks-read` - - `cpe-management-isolated-networks-write` - - `cpe-management-isolated-networks-primary-read` - - `cpe-management-isolated-networks-primary-write` - - `cpe-management-isolated-networks-auxiliary-read` - - `cpe-management-isolated-networks-auxiliary-write` + - `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: @@ -2478,8 +2480,8 @@ components: description: | Output with the following scope(s): - **any of** - - `cpe-management-devices-read` - - `cpe-management-devices-write` + - `network-access-management:devices:read` + - `network-access-management:devices:write` value: - *base-device - id: *device-id2 @@ -2490,24 +2492,24 @@ components: summary: Device List with Hardware Address description: | Output with the following scope(s): - - `cpe-management-devices-hardware-address-read` + - `network-access-management:devices.hardware-address:read` value: - - *device-with-hardware-address + - *device-with.hardware-address - id: *device-id2 name: *device-name2 description: *device-description2 - hardwareAddress: *device-hardware-address2 + hardwareAddress: *device.hardware-address2 DeviceListWithServiceSite: summary: Device List with Service Site description: | Output with the following scope(s): - **any of** - - `cpe-management-devices-read` - - `cpe-management-devices-write` + - `network-access-management:devices:read` + - `network-access-management:devices:write` - **any of** - - `cpe-management-service-sites-read` - - `cpe-management-service-sites-location-read` + - `network-access-management:service-sites:read` + - `network-access-management:service-sites.location:read` value: - *device-with-service-site - id: *device-id2 @@ -2520,15 +2522,15 @@ components: description: | Output with the following scope(s): - **any of** - - `cpe-management-devices-read` - - `cpe-management-devices-write` + - `network-access-management:devices:read` + - `network-access-management:devices:write` - **any of** - - `cpe-management-isolated-networks-read` - - `cpe-management-isolated-networks-write` - - `cpe-management-isolated-networks-primary-read` - - `cpe-management-isolated-networks-primary-write` - - `cpe-management-isolated-networks-auxiliary-read` - - `cpe-management-isolated-networks-auxiliary-write` + - `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 @@ -2541,36 +2543,36 @@ components: summary: Device List with Hardware Address and Service Site description: | Output with the following scope(s): - - `cpe-management-devices-hardware-address-read` + - `network-access-management:devices.hardware-address:read` - **any of** - - `cpe-management-service-sites-read` - - `cpe-management-service-sites-location-read` + - `network-access-management:service-sites:read` + - `network-access-management:service-sites.location:read` value: - - *device-with-hardware-address-and-service-site + - *device-with.hardware-address-and-service-site - id: *device-id2 name: *device-name2 description: *device-description2 - hardwareAddress: *device-hardware-address2 + hardwareAddress: *device.hardware-address2 serviceSite: *service-site-id2 DeviceListWithHardwareAddressAndNetworks: summary: Device List with Hardware Address and Networks description: | Output with the following scope(s): - - `cpe-management-devices-hardware-address-read` - - **any of** - - `cpe-management-isolated-networks-read` - - `cpe-management-isolated-networks-write` - - `cpe-management-isolated-networks-primary-read` - - `cpe-management-isolated-networks-primary-write` - - `cpe-management-isolated-networks-auxiliary-read` - - `cpe-management-isolated-networks-auxiliary-write` + - `network-access-management:devices.hardware-address:read` + - **any 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 + - *device-with.hardware-address-and-networks - id: *device-id2 name: *device-name2 description: *device-description2 - hardwareAddress: *device-hardware-address2 + hardwareAddress: *device.hardware-address2 networks: *device-network-intersection-list maxAuxiliaryNetworks: *device-max-networks2 @@ -2579,18 +2581,18 @@ components: description: | Output with the following scope(s): - **any of** - - `cpe-management-devices-read` - - `cpe-management-devices-write` + - `network-access-management:devices:read` + - `network-access-management:devices:write` - **any of** - - `cpe-management-service-sites-read` - - `cpe-management-service-sites-location-read` + - `network-access-management:service-sites:read` + - `network-access-management:service-sites.location:read` - **any of** - - `cpe-management-isolated-networks-read` - - `cpe-management-isolated-networks-write` - - `cpe-management-isolated-networks-primary-read` - - `cpe-management-isolated-networks-primary-write` - - `cpe-management-isolated-networks-auxiliary-read` - - `cpe-management-isolated-networks-auxiliary-write` + - `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 @@ -2604,17 +2606,17 @@ components: summary: Device List with Hardware Address, Service Site, and Networks description: | Output with the following scope(s): - - `cpe-management-devices-hardware-address-read` + - `network-access-management:devices.hardware-address:read` - **any of** - - `cpe-management-service-sites-read` - - `cpe-management-service-sites-location-read` + - `network-access-management:service-sites:read` + - `network-access-management:service-sites.location:read` - **any of** - - `cpe-management-isolated-networks-read` - - `cpe-management-isolated-networks-write` - - `cpe-management-isolated-networks-primary-read` - - `cpe-management-isolated-networks-primary-write` - - `cpe-management-isolated-networks-auxiliary-read` - - `cpe-management-isolated-networks-auxiliary-write` + - `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: @@ -2622,12 +2624,12 @@ components: description: | Output with the following scope(s): - **any of** - - `cpe-management-isolated-networks-read` - - `cpe-management-isolated-networks-write` - - `cpe-management-isolated-networks-primary-read` - - `cpe-management-isolated-networks-primary-write` - - `cpe-management-isolated-networks-auxiliary-read` - - `cpe-management-isolated-networks-auxiliary-write` + - `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 @@ -2644,16 +2646,16 @@ components: description: | Output with the following scope(s): - **any of** - - `cpe-management-isolated-networks-read` - - `cpe-management-isolated-networks-write` - - `cpe-management-isolated-networks-primary-read` - - `cpe-management-isolated-networks-primary-write` - - `cpe-management-isolated-networks-auxiliary-read` - - `cpe-management-isolated-networks-auxiliary-write` + - `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` - **any of** - - `cpe-management-devices-read` - - `cpe-management-devices-write` - - `cpe-management-devices-hardware-address-read` + - `network-access-management:devices:read` + - `network-access-management:devices:write` + - `network-access-management:devices.hardware-address:read` value: *network NetworkUpdate: @@ -2661,9 +2663,9 @@ components: description: | Post with the following scope(s): - **any of** - - `cpe-management-isolated-networks-write` - - `cpe-management-isolated-networks-primary-write` - - `cpe-management-isolated-networks-auxiliary-write` + - `network-access-management:isolated-networks:write` + - `network-access-management:isolated-networks.primary:write` + - `network-access-management:isolated-networks.auxiliary:write` value: *network-update BaseNetworkCreate: @@ -2671,9 +2673,9 @@ components: description: | Post with the following scope(s): - **any of** - - `cpe-management-isolated-networks-write` - - `cpe-management-isolated-networks-primary-write` - - `cpe-management-isolated-networks-auxiliary-write` + - `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 @@ -2684,10 +2686,10 @@ components: description: | Post with the following scope(s): - **any of** - - `cpe-management-isolated-networks-write` - - `cpe-management-isolated-networks-primary-write` - - `cpe-management-isolated-networks-auxiliary-write` - - `cpe-management-devices-write` + - `network-access-management:isolated-networks:write` + - `network-access-management:isolated-networks.primary:write` + - `network-access-management:isolated-networks.auxiliary:write` + - `network-access-management:devices:write` value: *network-create BaseNetworkList: @@ -2695,12 +2697,12 @@ components: description: | Output with the following scope(s): - **any of** - - `cpe-management-isolated-networks-read` - - `cpe-management-isolated-networks-write` - - `cpe-management-isolated-networks-primary-read` - - `cpe-management-isolated-networks-primary-write` - - `cpe-management-isolated-networks-auxiliary-read` - - `cpe-management-isolated-networks-auxiliary-write` + - `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 @@ -2718,16 +2720,16 @@ components: description: | Output with the following scope(s): - **any of** - - `cpe-management-isolated-networks-read` - - `cpe-management-isolated-networks-write` - - `cpe-management-isolated-networks-primary-read` - - `cpe-management-isolated-networks-primary-write` - - `cpe-management-isolated-networks-auxiliary-read` - - `cpe-management-isolated-networks-auxiliary-write` + - `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` - **any of** - - `cpe-management-devices-read` - - `cpe-management-devices-write` - - `cpe-management-devices-hardware-address-read` + - `network-access-management:devices:read` + - `network-access-management:devices:write` + - `network-access-management:devices.hardware-address:read` value: *network-list BaseRebootRequest: @@ -2735,8 +2737,8 @@ components: description: | Output with the following scope(s): - **any of** - - `cpe-management-reboot-requests-read` - - `cpe-management-reboot-requests-write` + - `network-access-management:reboot-requests:read` + - `network-access-management:reboot-requests:write` value: &base-reboot-request id: *reboot-id message: *reboot-message @@ -2751,12 +2753,12 @@ components: description: | Output with the following scope(s): - **any of** - - `cpe-management-reboot-requests-read` - - `cpe-management-reboot-requests-write` + - `network-access-management:reboot-requests:read` + - `network-access-management:reboot-requests:write` - **any of** - - `cpe-management-devices-read` - - `cpe-management-devices-write` - - `cpe-management-devices-hardware-address-read` + - `network-access-management:devices:read` + - `network-access-management:devices:write` + - `network-access-management:devices.hardware-address:read` value: *reboot-request RebootRequestUpdate: @@ -2764,7 +2766,7 @@ components: description: | Post with the following scope(s): - **any of** - - `cpe-management-reboot-requests-write` + - `network-access-management:reboot-requests:write` value: *reboot-request-update BaseRebootRequestCreate: @@ -2772,7 +2774,7 @@ components: description: | Post with the following scope(s): - **any of** - - `cpe-management-reboot-requests-write` + - `network-access-management:reboot-requests:write` value: &reboot-request-update message: *reboot-message atTime: *date-time @@ -2782,8 +2784,8 @@ components: description: | Post with the following scope(s): - **any of** - - `cpe-management-reboot-requests-write` - - `cpe-management-devices-write` + - `network-access-management:reboot-requests:write` + - `network-access-management:devices:write` value: *reboot-create BaseRebootRequestList: @@ -2791,8 +2793,8 @@ components: description: | Output with the following scope(s): - **any of** - - `cpe-management-reboot-requests-read` - - `cpe-management-reboot-requests-write` + - `network-access-management:reboot-requests:read` + - `network-access-management:reboot-requests:write` value: - *base-reboot-request - id: *reboot-id2 @@ -2808,12 +2810,12 @@ components: description: | Output with the following scope(s): - **any of** - - `cpe-management-reboot-requests-read` - - `cpe-management-reboot-requests-write` + - `network-access-management:reboot-requests:read` + - `network-access-management:reboot-requests:write` - **any of** - - `cpe-management-devices-read` - - `cpe-management-devices-write` - - `cpe-management-devices-hardware-address-read` + - `network-access-management:devices:read` + - `network-access-management:devices:write` + - `network-access-management:devices.hardware-address:read` value: *reboot-request-list responses: From 258a3f85487d737a28dcb9a32d0d7070b4ce4d0a Mon Sep 17 00:00:00 2001 From: Christopher Aubut Date: Fri, 5 Jul 2024 15:20:38 -0600 Subject: [PATCH 25/30] fix: fixes linting issues --- .../network_access_management.yaml | 27 ++++++++++--------- 1 file changed, 14 insertions(+), 13 deletions(-) diff --git a/code/API_definitions/network_access_management.yaml b/code/API_definitions/network_access_management.yaml index a72e7d6..8367c0a 100644 --- a/code/API_definitions/network_access_management.yaml +++ b/code/API_definitions/network_access_management.yaml @@ -278,6 +278,7 @@ paths: 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. @@ -1765,19 +1766,19 @@ components: hardwareAddressType: type: string enum: ["EUI-48"] - example: &device.hardware-address-type "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" + 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 + example: &device-hardware-address + hardwareAddressType: *device-hardware-address-type + value: *device-hardware-address-value serviceSite: $ref: "#/components/schemas/ServiceSiteId" networks: @@ -1800,7 +1801,7 @@ components: id: *device-id name: *device-name description: *device-description - hardwareAddress: *device.hardware-address + hardwareAddress: *device-hardware-address serviceSite: *service-site-id networks: *device-network-intersection-list maxAuxiliaryNetworks: *device-max-networks @@ -1814,7 +1815,7 @@ components: - id: *device-id2 name: &device-name2 "Gateway-2" description: &device-description2 "A second Wi-Fi gateway devices" - hardwareAddress: &device.hardware-address2 + hardwareAddress: &device-hardware-address2 hardwareAddressType: "EUI-48" value: "AB:CD:EF:12:34:56" serviceSite: *service-site-id2 @@ -2359,7 +2360,7 @@ components: id: *device-id name: *device-name description: *device-description - hardwareAddress: *device.hardware-address + hardwareAddress: *device-hardware-address DeviceWithServiceSite: summary: Device with Service Site @@ -2410,7 +2411,7 @@ components: id: *device-id name: *device-name description: *device-description - hardwareAddress: *device.hardware-address + hardwareAddress: *device-hardware-address serviceSite: *service-site-id DeviceWithHardwareAddressAndNetworks: @@ -2429,7 +2430,7 @@ components: id: *device-id name: *device-name description: *device-description - hardwareAddress: *device.hardware-address + hardwareAddress: *device-hardware-address networks: *device-network-intersection-list maxAuxiliaryNetworks: *device-max-networks @@ -2498,7 +2499,7 @@ components: - id: *device-id2 name: *device-name2 description: *device-description2 - hardwareAddress: *device.hardware-address2 + hardwareAddress: *device-hardware-address2 DeviceListWithServiceSite: summary: Device List with Service Site @@ -2552,7 +2553,7 @@ components: - id: *device-id2 name: *device-name2 description: *device-description2 - hardwareAddress: *device.hardware-address2 + hardwareAddress: *device-hardware-address2 serviceSite: *service-site-id2 DeviceListWithHardwareAddressAndNetworks: @@ -2572,7 +2573,7 @@ components: - id: *device-id2 name: *device-name2 description: *device-description2 - hardwareAddress: *device.hardware-address2 + hardwareAddress: *device-hardware-address2 networks: *device-network-intersection-list maxAuxiliaryNetworks: *device-max-networks2 From 8b5875273692743c2a1d6e0986d3a633e79ed98a Mon Sep 17 00:00:00 2001 From: Christopher Aubut Date: Fri, 5 Jul 2024 15:30:38 -0600 Subject: [PATCH 26/30] chore: partially updates endpoint security defs to commonalities spec --- .../network_access_management.yaml | 333 ++++++++++-------- 1 file changed, 183 insertions(+), 150 deletions(-) diff --git a/code/API_definitions/network_access_management.yaml b/code/API_definitions/network_access_management.yaml index 8367c0a..6f21653 100644 --- a/code/API_definitions/network_access_management.yaml +++ b/code/API_definitions/network_access_management.yaml @@ -172,15 +172,13 @@ paths: security: - openId: - network-access-management:service-sites:read - - network-access-management:service-sites.location:read - - network-access-management:devices:read operationId: getServiceSites description: | Returns all service sites. Scopes impact the output of this endpoint. See the examples for various permutations. **Required Scopes:** - - **any of** + - **one of** - `network-access-management:service-sites:read` - `network-access-management:service-sites.location:read` @@ -229,7 +227,7 @@ paths: for various permutations. **Required Scopes:** - - **any of** + - **one of** - `network-access-management:service-sites:read` - `network-access-management:service-sites.location:read` @@ -285,13 +283,14 @@ paths: See the examples for various permutations. **Required Scopes:** - - **any of** - - `network-access-management:service-sites:read` - - `network-access-management:service-sites.location:read` - - **any of** - - `network-access-management:devices:read` - - `network-access-management:devices:write` - - `network-access-management:devices.hardware-address:read` + - **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` @@ -339,25 +338,31 @@ paths: 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:** - - **any of** - - `network-access-management:service-sites:read` - - `network-access-management:service-sites.location:read` - - **any of** - - `network-access-management:devices:read` - - `network-access-management:devices:write` - - `network-access-management:devices.hardware-address:read` - - **any 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` + - **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: @@ -390,18 +395,21 @@ paths: 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:** - - **any of** + - **one of** - `network-access-management:devices:read` - `network-access-management:devices:write` - `network-access-management:devices.hardware-address:read` **Optional Scopes:** - - **any of** + - **one of** - `network-access-management:service-sites:read` - `network-access-management:service-sites.location:read` - `network-access-management:isolated-networks:read` @@ -450,19 +458,22 @@ paths: 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:** - - **any of** + - **one of** - `network-access-management:devices:read` - `network-access-management:devices:write` - `network-access-management:devices.hardware-address:read` **Optional Scopes:** - - **any of** + - **one of** - `network-access-management:service-sites:read` - `network-access-management:service-sites.location:read` - `network-access-management:isolated-networks:read` @@ -517,23 +528,28 @@ paths: 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:** - - **any of** - - `network-access-management:devices:read` - - `network-access-management:devices:write` - - `network-access-management:devices.hardware-address:read` - - **any 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` + - **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: @@ -565,6 +581,10 @@ paths: 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. @@ -573,14 +593,15 @@ paths: is replaced and is no longer assigned to any device, it is considered automatically deleted. **Required Scopes:** - - `network-access-management:devices:write` - - **any 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` + - **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: @@ -612,13 +633,16 @@ paths: 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:** - - **any of** + - **one of** - `network-access-management:isolated-networks:read` - `network-access-management:isolated-networks:write` - `network-access-management:isolated-networks.primary:read` @@ -628,17 +652,18 @@ paths: ## Without Default Device **Required Scopes:** - - **any 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` - - **any of** - - `network-access-management:devices:read` - - `network-access-management:devices:write` - - `network-access-management:devices.hardware-address:read` + - **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": @@ -668,6 +693,9 @@ paths: - 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. @@ -678,7 +706,7 @@ paths: MUST be set to `undefined`. **Required Scopes:** - - **any of** + - **one of** - `network-access-management:isolated-networks:write` - `network-access-management:isolated-networks.primary:write` - `network-access-management:isolated-networks.auxiliary:write` @@ -687,11 +715,12 @@ paths: Create the network and configure it to one or more devices. The `devices` field MUST NOT be empty. **Required Scopes:** - - `network-access-management:devices:write` - - **any of** - - `network-access-management:isolated-networks:write` - - `network-access-management:isolated-networks.primary:write` - - `network-access-management:isolated-networks.auxiliary:write` + - **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: @@ -733,6 +762,9 @@ paths: 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 @@ -740,7 +772,7 @@ paths: ## With Default Device **Required Scopes:** - - **any of** + - **one of** - `network-access-management:isolated-networks:read` - `network-access-management:isolated-networks:write` - `network-access-management:isolated-networks.primary:read` @@ -750,17 +782,18 @@ paths: ## Without Default Device **Required Scopes:** - - **any 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` - - **any of** - - `network-access-management:devices:read` - - `network-access-management:devices:write` - - `network-access-management:devices.hardware-address:read` + - **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: @@ -801,7 +834,7 @@ paths: ## With Default Device **Required Scopes:** - - **any of** + - **one of** - `network-access-management:isolated-networks:write` - `network-access-management:isolated-networks.primary:write` - `network-access-management:isolated-networks.auxiliary:write` @@ -809,7 +842,7 @@ paths: ## Without Default Device **Required Scopes:** - `network-access-management:devices:write` - - **any of** + - **one of** - `network-access-management:isolated-networks:write` - `network-access-management:isolated-networks.primary:write` - `network-access-management:isolated-networks.auxiliary:write` @@ -862,7 +895,7 @@ paths: ## With Default Device **Required Scopes:** - - **any of** + - **one of** - `network-access-management:isolated-networks:write` - `network-access-management:isolated-networks.primary:write` - `network-access-management:isolated-networks.auxiliary:write` @@ -870,7 +903,7 @@ paths: ## Without Default Device **Required Scopes:** - `network-access-management:devices:write` - - **any of** + - **one of** - `network-access-management:isolated-networks:write` - `network-access-management:isolated-networks.primary:write` - `network-access-management:isolated-networks.auxiliary:write` @@ -905,11 +938,11 @@ paths: endpoint. See the examples for various permutations. **Required Scopes:** - - **any of** + - **one of** - `network-access-management:devices:read` - `network-access-management:devices:write` - `network-access-management:devices.hardware-address:read` - - **any of** + - **one of** - `network-access-management:isolated-networks:read` - `network-access-management:isolated-networks:write` - `network-access-management:isolated-networks.primary:read` @@ -918,7 +951,7 @@ paths: - `network-access-management:isolated-networks.auxiliary:write` **Optional Scopes:** - - **any of** + - **one of** - `network-access-management:service-sites:read` - `network-access-management:service-sites.location:read` parameters: @@ -964,7 +997,7 @@ paths: **Required Scopes:** - `network-access-management:devices:write` - - **any of** + - **one of** - `network-access-management:isolated-networks:read` - `network-access-management:isolated-networks:write` - `network-access-management:isolated-networks.primary:read` @@ -1009,16 +1042,16 @@ paths: ## With Default Device **Required Scopes:** - - **any of** + - **one of** - `network-access-management:reboot-requests:read` - `network-access-management:reboot-requests:write` ## Without Default Device **Required Scopes:** - - **any of** + - **one of** - `network-access-management:reboot-requests:read` - `network-access-management:reboot-requests:write` - - **any of** + - **one of** - `network-access-management:devices:read` - `network-access-management:devices:write` - `network-access-management:devices.hardware-address:read` @@ -1059,7 +1092,7 @@ paths: one service location. The `devices` field MUST NOT be set or it MUST be set to `undefined`. **Required Scopes:** - - **any of** + - **one of** - `network-access-management:reboot-requests:write` ## Without Default Device @@ -1068,7 +1101,7 @@ paths: **Required Scopes:** - `network-access-management:devices:write` - - **any of** + - **one of** - `network-access-management:reboot-requests:write` requestBody: required: true @@ -1118,16 +1151,16 @@ paths: ## With Default Device **Required Scopes:** - - **any of** + - **one of** - `network-access-management:reboot-requests:read` - `network-access-management:reboot-requests:write` ## Without Default Device **Required Scopes:** - - **any of** + - **one of** - `network-access-management:reboot-requests:read` - `network-access-management:reboot-requests:write` - - **any of** + - **one of** - `network-access-management:devices:read` - `network-access-management:devices:write` - `network-access-management:devices.hardware-address:read` @@ -1172,13 +1205,13 @@ paths: ## With Default Device **Required Scopes:** - - **any of** + - **one of** - `network-access-management:reboot-requests:write` ## Without Default Device **Required Scopes:** - `network-access-management:devices:write` - - **any of** + - **one of** - `network-access-management:reboot-requests:write` parameters: - $ref: "#/components/parameters/rebootId" @@ -1228,13 +1261,13 @@ paths: ## With Default Device **Required Scopes:** - - **any of** + - **one of** - `network-access-management:reboot-requests:write` ## Without Default Device **Required Scopes:** - `network-access-management:devices:write` - - **any of** + - **one of** - `network-access-management:reboot-requests:write` parameters: - $ref: "#/components/parameters/rebootId" @@ -2274,7 +2307,7 @@ components: description: | Output with the following scope(s): - `network-access-management:service-sites:read` - - **any of** + - **one of** - `network-access-management:devices:read` - `network-access-management:devices:write` - `network-access-management:devices.hardware-address:read` @@ -2287,7 +2320,7 @@ components: description: | Output with the following scope(s): - `network-access-management:service-sites.location:read` - - **any of** + - **one of** - `network-access-management:devices:read` - `network-access-management:devices:write` - `network-access-management:devices.hardware-address:read` @@ -2319,7 +2352,7 @@ components: description: | Output with the following scope(s): - `network-access-management:service-sites:read` - - **any of** + - **one of** - `network-access-management:devices:read` - `network-access-management:devices:write` - `network-access-management:devices.hardware-address:read` @@ -2333,7 +2366,7 @@ components: description: | Output with the following scope(s): - `network-access-management:service-sites.location:read` - - **any of** + - **one of** - `network-access-management:devices:read` - `network-access-management:devices:write` - `network-access-management:devices.hardware-address:read` @@ -2343,7 +2376,7 @@ components: summary: Base Device description: | Output with the following scope(s): - - **any of** + - **one of** - `network-access-management:devices:read` - `network-access-management:devices:write` value: &base-device @@ -2356,7 +2389,7 @@ components: description: | Output with the following scope(s): - `network-access-management:devices.hardware-address:read` - value: &device-with.hardware-address + value: &device-with-hardware-address id: *device-id name: *device-name description: *device-description @@ -2366,10 +2399,10 @@ components: summary: Device with Service Site description: | Output with the following scope(s): - - **any of** + - **one of** - `network-access-management:devices:read` - `network-access-management:devices:write` - - **any of** + - **one of** - `network-access-management:service-sites:read` - `network-access-management:service-sites.location:read` value: &device-with-service-site @@ -2382,10 +2415,10 @@ components: summary: Device with Networks description: | Output with the following scope(s): - - **any of** + - **one of** - `network-access-management:devices:read` - `network-access-management:devices:write` - - **any of** + - **one of** - `network-access-management:isolated-networks:read` - `network-access-management:isolated-networks:write` - `network-access-management:isolated-networks.primary:read` @@ -2404,10 +2437,10 @@ components: description: | Output with the following scope(s): - `network-access-management:devices.hardware-address:read` - - **any of** + - **one of** - `network-access-management:service-sites:read` - `network-access-management:service-sites.location:read` - value: &device-with.hardware-address-and-service-site + value: &device-with-hardware-address-and-service-site id: *device-id name: *device-name description: *device-description @@ -2419,14 +2452,14 @@ components: description: | Output with the following scope(s): - `network-access-management:devices.hardware-address:read` - - **any 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` - value: &device-with.hardware-address-and-networks + value: &device-with-hardware-address-and-networks id: *device-id name: *device-name description: *device-description @@ -2438,13 +2471,13 @@ components: summary: Device with Service Site and Networks description: | Output with the following scope(s): - - **any of** + - **one of** - `network-access-management:devices:read` - `network-access-management:devices:write` - - **any of** + - **one of** - `network-access-management:service-sites:read` - `network-access-management:service-sites.location:read` - - **any of** + - **one of** - `network-access-management:isolated-networks:read` - `network-access-management:isolated-networks:write` - `network-access-management:isolated-networks.primary:read` @@ -2464,10 +2497,10 @@ components: description: | Output with the following scope(s): - `network-access-management:devices.hardware-address:read` - - **any of** + - **one of** - `network-access-management:service-sites:read` - `network-access-management:service-sites.location:read` - - **any of** + - **one of** - `network-access-management:isolated-networks:read` - `network-access-management:isolated-networks:write` - `network-access-management:isolated-networks.primary:read` @@ -2480,7 +2513,7 @@ components: summary: Base Device List description: | Output with the following scope(s): - - **any of** + - **one of** - `network-access-management:devices:read` - `network-access-management:devices:write` value: @@ -2495,7 +2528,7 @@ components: Output with the following scope(s): - `network-access-management:devices.hardware-address:read` value: - - *device-with.hardware-address + - *device-with-hardware-address - id: *device-id2 name: *device-name2 description: *device-description2 @@ -2505,10 +2538,10 @@ components: summary: Device List with Service Site description: | Output with the following scope(s): - - **any of** + - **one of** - `network-access-management:devices:read` - `network-access-management:devices:write` - - **any of** + - **one of** - `network-access-management:service-sites:read` - `network-access-management:service-sites.location:read` value: @@ -2522,10 +2555,10 @@ components: summary: Device List with Networks description: | Output with the following scope(s): - - **any of** + - **one of** - `network-access-management:devices:read` - `network-access-management:devices:write` - - **any of** + - **one of** - `network-access-management:isolated-networks:read` - `network-access-management:isolated-networks:write` - `network-access-management:isolated-networks.primary:read` @@ -2545,11 +2578,11 @@ components: description: | Output with the following scope(s): - `network-access-management:devices.hardware-address:read` - - **any of** + - **one of** - `network-access-management:service-sites:read` - `network-access-management:service-sites.location:read` value: - - *device-with.hardware-address-and-service-site + - *device-with-hardware-address-and-service-site - id: *device-id2 name: *device-name2 description: *device-description2 @@ -2561,7 +2594,7 @@ components: description: | Output with the following scope(s): - `network-access-management:devices.hardware-address:read` - - **any of** + - **one of** - `network-access-management:isolated-networks:read` - `network-access-management:isolated-networks:write` - `network-access-management:isolated-networks.primary:read` @@ -2569,7 +2602,7 @@ components: - `network-access-management:isolated-networks.auxiliary:read` - `network-access-management:isolated-networks.auxiliary:write` value: - - *device-with.hardware-address-and-networks + - *device-with-hardware-address-and-networks - id: *device-id2 name: *device-name2 description: *device-description2 @@ -2581,13 +2614,13 @@ components: summary: Device List with Service Site and Networks description: | Output with the following scope(s): - - **any of** + - **one of** - `network-access-management:devices:read` - `network-access-management:devices:write` - - **any of** + - **one of** - `network-access-management:service-sites:read` - `network-access-management:service-sites.location:read` - - **any of** + - **one of** - `network-access-management:isolated-networks:read` - `network-access-management:isolated-networks:write` - `network-access-management:isolated-networks.primary:read` @@ -2608,10 +2641,10 @@ components: description: | Output with the following scope(s): - `network-access-management:devices.hardware-address:read` - - **any of** + - **one of** - `network-access-management:service-sites:read` - `network-access-management:service-sites.location:read` - - **any of** + - **one of** - `network-access-management:isolated-networks:read` - `network-access-management:isolated-networks:write` - `network-access-management:isolated-networks.primary:read` @@ -2624,7 +2657,7 @@ components: summary: Network Configuration with Default Device description: | Output with the following scope(s): - - **any of** + - **one of** - `network-access-management:isolated-networks:read` - `network-access-management:isolated-networks:write` - `network-access-management:isolated-networks.primary:read` @@ -2646,14 +2679,14 @@ components: summary: Network Configuration description: | Output with the following scope(s): - - **any 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` - - **any of** + - **one of** - `network-access-management:devices:read` - `network-access-management:devices:write` - `network-access-management:devices.hardware-address:read` @@ -2663,7 +2696,7 @@ components: summary: Network Update description: | Post with the following scope(s): - - **any of** + - **one of** - `network-access-management:isolated-networks:write` - `network-access-management:isolated-networks.primary:write` - `network-access-management:isolated-networks.auxiliary:write` @@ -2673,7 +2706,7 @@ components: summary: Create Network on Default Device description: | Post with the following scope(s): - - **any of** + - **one of** - `network-access-management:isolated-networks:write` - `network-access-management:isolated-networks.primary:write` - `network-access-management:isolated-networks.auxiliary:write` @@ -2686,7 +2719,7 @@ components: summary: Create Network on Devices description: | Post with the following scope(s): - - **any of** + - **one of** - `network-access-management:isolated-networks:write` - `network-access-management:isolated-networks.primary:write` - `network-access-management:isolated-networks.auxiliary:write` @@ -2697,7 +2730,7 @@ components: summary: Network List with Default Device description: | Output with the following scope(s): - - **any of** + - **one of** - `network-access-management:isolated-networks:read` - `network-access-management:isolated-networks:write` - `network-access-management:isolated-networks.primary:read` @@ -2720,14 +2753,14 @@ components: summary: Network List with Devices description: | Output with the following scope(s): - - **any 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` - - **any of** + - **one of** - `network-access-management:devices:read` - `network-access-management:devices:write` - `network-access-management:devices.hardware-address:read` @@ -2737,7 +2770,7 @@ components: summary: Reboot Request with Default Device description: | Output with the following scope(s): - - **any of** + - **one of** - `network-access-management:reboot-requests:read` - `network-access-management:reboot-requests:write` value: &base-reboot-request @@ -2753,10 +2786,10 @@ components: summary: Reboot Request description: | Output with the following scope(s): - - **any of** + - **one of** - `network-access-management:reboot-requests:read` - `network-access-management:reboot-requests:write` - - **any of** + - **one of** - `network-access-management:devices:read` - `network-access-management:devices:write` - `network-access-management:devices.hardware-address:read` @@ -2766,7 +2799,7 @@ components: summary: Reboot Request Update description: | Post with the following scope(s): - - **any of** + - **one of** - `network-access-management:reboot-requests:write` value: *reboot-request-update @@ -2774,7 +2807,7 @@ components: summary: Create Reboot Request for Default Device description: | Post with the following scope(s): - - **any of** + - **one of** - `network-access-management:reboot-requests:write` value: &reboot-request-update message: *reboot-message @@ -2784,7 +2817,7 @@ components: summary: Create Reboot Request for Devices description: | Post with the following scope(s): - - **any of** + - **one of** - `network-access-management:reboot-requests:write` - `network-access-management:devices:write` value: *reboot-create @@ -2793,7 +2826,7 @@ components: summary: Reboot Request List with Default Device description: | Output with the following scope(s): - - **any of** + - **one of** - `network-access-management:reboot-requests:read` - `network-access-management:reboot-requests:write` value: @@ -2810,10 +2843,10 @@ components: summary: Reboot Request List description: | Output with the following scope(s): - - **any of** + - **one of** - `network-access-management:reboot-requests:read` - `network-access-management:reboot-requests:write` - - **any of** + - **one of** - `network-access-management:devices:read` - `network-access-management:devices:write` - `network-access-management:devices.hardware-address:read` From 73f6a4f0e3ce3f73b4dd23b6956e2d1f0126fcfa Mon Sep 17 00:00:00 2001 From: Christopher Aubut Date: Fri, 5 Jul 2024 15:42:20 -0600 Subject: [PATCH 27/30] fix: fixes linting issues --- code/API_definitions/network_access_management.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/code/API_definitions/network_access_management.yaml b/code/API_definitions/network_access_management.yaml index 6f21653..15cca27 100644 --- a/code/API_definitions/network_access_management.yaml +++ b/code/API_definitions/network_access_management.yaml @@ -583,8 +583,8 @@ paths: 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 + - 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. From f8c1a2a36f321a25b0c26b51f8c73a06e98aded3 Mon Sep 17 00:00:00 2001 From: Christopher Aubut Date: Fri, 5 Jul 2024 15:43:29 -0600 Subject: [PATCH 28/30] fix: fixes linting issues --- .../network_access_management.yaml | 26 +++++++++---------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/code/API_definitions/network_access_management.yaml b/code/API_definitions/network_access_management.yaml index 15cca27..d77f7a7 100644 --- a/code/API_definitions/network_access_management.yaml +++ b/code/API_definitions/network_access_management.yaml @@ -171,7 +171,7 @@ paths: summary: Get all service sites security: - openId: - - network-access-management:service-sites:read + - 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 @@ -220,7 +220,7 @@ paths: summary: Get a service site by ID security: - openId: - - network-access-management:service-sites:read + - 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 @@ -275,8 +275,8 @@ paths: summary: Get all devices at a service site security: - openId: - - network-access-management:service-sites:read - - network-access-management:devices:read + - 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. @@ -340,9 +340,9 @@ paths: 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 + - 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. @@ -397,7 +397,7 @@ paths: summary: Get all devices security: - openId: - - network-access-management:devices:read + - network-access-management:devices:read operationId: getDevices description: | Returns all devices. Scopes impact the output of this endpoint. See the examples for various permutations. @@ -460,7 +460,7 @@ paths: summary: Get a device by ID security: - openId: - - network-access-management:devices:read + - 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 @@ -530,8 +530,8 @@ paths: summary: Get all networks configured on a device security: - openId: - - network-access-management:devices:read - - network-access-management:isolated-networks:read + - 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 @@ -635,7 +635,7 @@ paths: summary: Get all Networks security: - openId: - - network-access-management:isolated-networks:read + - 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. @@ -695,7 +695,7 @@ paths: operationId: createNetwork security: - openId: - - network-access-management:isolated-networks:write + - 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. From 12b947ae2a02be3af82dee5c0a1aafcb8396fa9f Mon Sep 17 00:00:00 2001 From: Christopher Aubut Date: Fri, 5 Jul 2024 16:10:08 -0600 Subject: [PATCH 29/30] fix: fixes linting issues --- .../network_access_management.yaml | 32 +++++++++---------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/code/API_definitions/network_access_management.yaml b/code/API_definitions/network_access_management.yaml index d77f7a7..b865531 100644 --- a/code/API_definitions/network_access_management.yaml +++ b/code/API_definitions/network_access_management.yaml @@ -171,7 +171,7 @@ paths: summary: Get all service sites security: - openId: - - network-access-management:service-sites:read + - 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 @@ -220,7 +220,7 @@ paths: summary: Get a service site by ID security: - openId: - - network-access-management:service-sites:read + - 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 @@ -275,8 +275,8 @@ paths: summary: Get all devices at a service site security: - openId: - - network-access-management:service-sites:read - - network-access-management:devices:read + - 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. @@ -340,9 +340,9 @@ paths: 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 + - 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. @@ -397,7 +397,7 @@ paths: summary: Get all devices security: - openId: - - network-access-management:devices:read + - network-access-management:devices:read operationId: getDevices description: | Returns all devices. Scopes impact the output of this endpoint. See the examples for various permutations. @@ -460,7 +460,7 @@ paths: summary: Get a device by ID security: - openId: - - network-access-management:devices:read + - 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 @@ -530,8 +530,8 @@ paths: summary: Get all networks configured on a device security: - openId: - - network-access-management:devices:read - - network-access-management:isolated-networks:read + - 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 @@ -583,8 +583,8 @@ paths: 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 + - 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. @@ -635,7 +635,7 @@ paths: summary: Get all Networks security: - openId: - - network-access-management:isolated-networks:read + - 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. @@ -695,7 +695,7 @@ paths: operationId: createNetwork security: - openId: - - network-access-management:isolated-networks:write + - 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. @@ -764,7 +764,7 @@ paths: summary: Get a Network by ID security: - openId: - - network-access-management:isolated-networks:read + - 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 From 9e3ae5d17b415dc3d6e342a29b30fc5e2f83de69 Mon Sep 17 00:00:00 2001 From: Christopher Aubut Date: Mon, 8 Jul 2024 13:16:43 -0600 Subject: [PATCH 30/30] chore: adds remaining sec defs --- .../network_access_management.yaml | 452 ++++++++++-------- 1 file changed, 255 insertions(+), 197 deletions(-) diff --git a/code/API_definitions/network_access_management.yaml b/code/API_definitions/network_access_management.yaml index b865531..d45ad66 100644 --- a/code/API_definitions/network_access_management.yaml +++ b/code/API_definitions/network_access_management.yaml @@ -178,14 +178,14 @@ paths: permutations. **Required Scopes:** - - **one of** - - `network-access-management:service-sites:read` - - `network-access-management:service-sites.location:read` + - **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` + - `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 @@ -227,14 +227,14 @@ paths: for various permutations. **Required Scopes:** - - **one of** - - `network-access-management:service-sites:read` - - `network-access-management:service-sites.location:read` + - **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` + - `network-access-management:devices:read` + - `network-access-management:devices:write` + - `network-access-management:devices.hardware-address:read` parameters: - $ref: "#/components/parameters/siteId" responses: @@ -283,23 +283,22 @@ paths: 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` + - **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` - + - `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: @@ -348,21 +347,21 @@ paths: 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` + - **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: @@ -403,21 +402,21 @@ paths: 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` + - **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` + - **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 @@ -467,21 +466,21 @@ paths: various permutations. **Required Scopes:** - - **one of** - - `network-access-management:devices:read` - - `network-access-management:devices:write` - - `network-access-management:devices.hardware-address:read` + - **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` + - **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: @@ -538,18 +537,18 @@ paths: 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` + - **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: @@ -593,15 +592,15 @@ paths: 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` + - **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: @@ -642,13 +641,13 @@ paths: ## 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` + - **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:** @@ -664,7 +663,6 @@ paths: - `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 @@ -706,21 +704,21 @@ paths: 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` + - **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` + - **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: @@ -772,6 +770,17 @@ paths: ## 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` @@ -779,21 +788,10 @@ paths: - `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` + - **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: @@ -827,6 +825,9 @@ paths: 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 @@ -834,13 +835,14 @@ paths: ## 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` + - **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` @@ -888,6 +890,9 @@ paths: 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 @@ -895,13 +900,14 @@ paths: ## 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` + - **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` @@ -932,12 +938,17 @@ paths: 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` @@ -951,9 +962,9 @@ paths: - `network-access-management:isolated-networks.auxiliary:write` **Optional Scopes:** - - **one of** - - `network-access-management:service-sites:read` - - `network-access-management:service-sites.location:read` + - **one of** + - `network-access-management:service-sites:read` + - `network-access-management:service-sites.location:read` parameters: - $ref: "#/components/parameters/netId" responses: @@ -991,12 +1002,17 @@ paths: 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:** - - `network-access-management:devices:write` + - **all of ** + - `network-access-management:devices:write` - **one of** - `network-access-management:isolated-networks:read` - `network-access-management:isolated-networks:write` @@ -1035,6 +1051,9 @@ paths: 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 @@ -1042,12 +1061,13 @@ paths: ## With Default Device **Required Scopes:** - - **one of** - - `network-access-management:reboot-requests:read` - - `network-access-management:reboot-requests:write` + - **one of** + - `network-access-management:reboot-requests:read` + - `network-access-management:reboot-requests:write` ## Without Default Device - **Required Scopes:** + **Required Scopes:** + - **all of** - **one of** - `network-access-management:reboot-requests:read` - `network-access-management:reboot-requests:write` @@ -1082,6 +1102,9 @@ paths: 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 @@ -1092,17 +1115,17 @@ paths: one service location. The `devices` field MUST NOT be set or it MUST be set to `undefined`. **Required Scopes:** - - **one of** - - `network-access-management:reboot-requests:write` + - **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` - - **one of** - - `network-access-management:reboot-requests:write` + - `network-access-management:reboot-requests:write` requestBody: required: true content: @@ -1144,6 +1167,9 @@ paths: 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 @@ -1151,12 +1177,13 @@ paths: ## With Default Device **Required Scopes:** - - **one of** - - `network-access-management:reboot-requests:read` - - `network-access-management:reboot-requests:write` + - **one of** + - `network-access-management:reboot-requests:read` + - `network-access-management:reboot-requests:write` ## Without Default Device - **Required Scopes:** + **Required Scopes:** + - **all off** - **one of** - `network-access-management:reboot-requests:read` - `network-access-management:reboot-requests:write` @@ -1197,6 +1224,9 @@ paths: 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 @@ -1205,14 +1235,14 @@ paths: ## With Default Device **Required Scopes:** - - **one of** - - `network-access-management:reboot-requests:write` + - **all of** + - `network-access-management:reboot-requests:write` ## Without Default Device **Required Scopes:** + - **all of** - `network-access-management:devices:write` - - **one of** - - `network-access-management:reboot-requests:write` + - `network-access-management:reboot-requests:write` parameters: - $ref: "#/components/parameters/rebootId" requestBody: @@ -1255,20 +1285,23 @@ paths: 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:** - - **one of** - - `network-access-management:reboot-requests:write` + - **all of** + - `network-access-management:reboot-requests:write` ## Without Default Device **Required Scopes:** + - **all of** - `network-access-management:devices:write` - - **one of** - - `network-access-management:reboot-requests:write` + - `network-access-management:reboot-requests:write` parameters: - $ref: "#/components/parameters/rebootId" responses: @@ -1693,8 +1726,8 @@ components: discriminator: propertyName: intersectionType mappings: - - NetworkDeviceRoleConfiguration: '#/components/schemas/NetworkDeviceRoleConfiguration' - - NetworkDeviceReplacement: '#/components/schemas/NetworkDeviceReplacement' + - NetworkDeviceRoleConfiguration: "#/components/schemas/NetworkDeviceRoleConfiguration" + - NetworkDeviceReplacement: "#/components/schemas/NetworkDeviceReplacement" example: &network-device-intersection-create intersectionType: *network-device-intersection-type device: *device-id @@ -2306,6 +2339,7 @@ components: 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` @@ -2319,6 +2353,7 @@ components: 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` @@ -2330,6 +2365,7 @@ components: summary: Base Service Site List description: | Output with the following scope(s): + - **all of** - `network-access-management:service-sites:read` value: - *base-service-site @@ -2339,6 +2375,7 @@ components: 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 @@ -2351,6 +2388,7 @@ components: 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` @@ -2365,6 +2403,7 @@ components: 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` @@ -2376,9 +2415,9 @@ components: summary: Base Device description: | Output with the following scope(s): - - **one of** - - `network-access-management:devices:read` - - `network-access-management:devices:write` + - **one of** + - `network-access-management:devices:read` + - `network-access-management:devices:write` value: &base-device id: *device-id name: *device-name @@ -2388,6 +2427,7 @@ components: 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 @@ -2399,6 +2439,7 @@ components: 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` @@ -2415,6 +2456,7 @@ components: 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` @@ -2436,6 +2478,7 @@ components: 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` @@ -2451,6 +2494,7 @@ components: 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` @@ -2471,6 +2515,7 @@ components: 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` @@ -2496,6 +2541,7 @@ components: 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` @@ -2513,9 +2559,9 @@ components: summary: Base Device List description: | Output with the following scope(s): - - **one of** - - `network-access-management:devices:read` - - `network-access-management:devices:write` + - **one of** + - `network-access-management:devices:read` + - `network-access-management:devices:write` value: - *base-device - id: *device-id2 @@ -2526,6 +2572,7 @@ components: 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 @@ -2538,6 +2585,7 @@ components: 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` @@ -2555,6 +2603,7 @@ components: 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` @@ -2577,6 +2626,7 @@ components: 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` @@ -2593,6 +2643,7 @@ components: 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` @@ -2614,6 +2665,7 @@ components: 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` @@ -2640,6 +2692,7 @@ components: 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` @@ -2657,13 +2710,13 @@ components: 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` + - **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 @@ -2679,6 +2732,7 @@ components: 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` @@ -2696,20 +2750,20 @@ components: 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` + - **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` + - **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 @@ -2719,24 +2773,25 @@ components: 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` - - `network-access-management:devices: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` + - **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 @@ -2753,6 +2808,7 @@ components: 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` @@ -2770,9 +2826,9 @@ components: 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` + - **one of** + - `network-access-management:reboot-requests:read` + - `network-access-management:reboot-requests:write` value: &base-reboot-request id: *reboot-id message: *reboot-message @@ -2786,6 +2842,7 @@ components: 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` @@ -2799,16 +2856,16 @@ components: summary: Reboot Request Update description: | Post with the following scope(s): - - **one of** - - `network-access-management:reboot-requests:write` + - **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): - - **one of** - - `network-access-management:reboot-requests:write` + - **all of** + - `network-access-management:reboot-requests:write` value: &reboot-request-update message: *reboot-message atTime: *date-time @@ -2817,18 +2874,18 @@ components: summary: Create Reboot Request for Devices description: | Post with the following scope(s): - - **one of** - - `network-access-management:reboot-requests:write` + - **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` + - **one of** + - `network-access-management:reboot-requests:read` + - `network-access-management:reboot-requests:write` value: - *base-reboot-request - id: *reboot-id2 @@ -2843,6 +2900,7 @@ components: 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`