diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..4c46b65 --- /dev/null +++ b/.gitignore @@ -0,0 +1,3 @@ +.DS_Store +.vscode/ +*-bundled.yaml \ No newline at end of file diff --git a/code/API_definitions/Domain/AccessDetail.yaml b/code/API_definitions/Domain/AccessDetail.yaml new file mode 100644 index 0000000..9eda720 --- /dev/null +++ b/code/API_definitions/Domain/AccessDetail.yaml @@ -0,0 +1,225 @@ +# This file defines the AccessDetail schema model for different network access types. +# It includes Wi-Fi and Thread access details with various security modes. + +components: + schemas: + # Base security mode schemas (unchanged) + WpaPersonalDetail: + type: object + description: WPA Personal security mode configuration for Wi-Fi networks. + properties: + password: + type: string + writeOnly: true + minLength: 8 + maxLength: 255 + pattern: "^[\\x20-\\x7E]{8,63}$" + 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" + additionalProperties: false + required: + - password + example: &wpa-personal + password: *wpa-personal-password + securityModeType: *wpa-personal-security-mode-type + + WpaEnterpriseDetail: + type: object + description: WPA Enterprise security mode configuration for Wi-Fi networks. + 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" + additionalProperties: false + required: + - securityModeType + example: &wpa-enterprise + authServer: *wpa-enterprise-auth-server + securityModeType: *wpa-enterprise-security-mode-type + + # Flattened concrete implementations for Wi-Fi + WiFiWpaPersonalAccessDetail: + type: object + description: Complete access details for Wi-Fi networks using WPA Personal security mode. + properties: + accessType: + type: string + description: The type of network access. + enum: + - "Wi-Fi:WPA_PERSONAL" + example: "Wi-Fi:WPA_PERSONAL" + ssid: + type: string + minLength: 2 + maxLength: 32 + pattern: "^(?! )[\\x20-\\x7E]{2,32}(?{}]{0,256}$ + example: "b4333c46-49c0-4f62-80d7-f0ef930f1c46" + TimePeriod: + properties: + startDate: + type: string + format: date-time + description: An instant of time, starting of the TimePeriod. It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone. + endDate: + type: string + format: date-time + description: An instant of time, ending of the TimePeriod. If not included, then the period has no ending date. It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone. + required: + - startDate + ErrorInfo: + type: object + required: + - status + - code + - message + properties: + status: + type: integer + description: HTTP response status code + code: + type: string + description: A human-readable code to describe the error + message: + type: string + description: A human-readable description of what the event represents + Device: + description: | + End-user equipment able to connect to a mobile network. Examples of devices include smartphones or IoT sensors/actuators. + The developer can choose to provide the below specified device identifiers: + * `ipv4Address` + * `ipv6Address` + * `phoneNumber` + * `networkAccessIdentifier` + NOTE1: the network operator might support only a subset of these options. The API invoker can provide multiple identifiers to be compatible across different network operators. In this case the identifiers MUST belong to the same device. + NOTE2: as for this Commonalities release, we are enforcing that the networkAccessIdentifier is only part of the schema for future-proofing, and CAMARA does not currently allow its use. After the CAMARA meta-release work is concluded and the relevant issues are resolved, its use will need to be explicitly documented in the guidelines. + type: object + properties: + phoneNumber: + $ref: "#/components/schemas/PhoneNumber" + networkAccessIdentifier: + $ref: "#/components/schemas/NetworkAccessIdentifier" + ipv4Address: + $ref: "#/components/schemas/DeviceIpv4Addr" + ipv6Address: + $ref: "#/components/schemas/DeviceIpv6Address" + minProperties: 1 + + DeviceResponse: + description: | + An identifier for the end-user equipment able to connect to the network that the response refers to. This parameter is only returned when the API consumer includes the `device` parameter in their request (i.e. they are using a two-legged access token), and is relevant when more than one device identifier is specified, as only one of those device identifiers is allowed in the response. + + If the API consumer provides more than one device identifier in their request, and this schema is included in the response definition, the API provider MUST use it to return a single identifier which is the one they are using to fulfil the request, even if the identifiers do not match the same device. API provider does not perform any logic to validate/correlate that the indicated device identifiers match the same device. No error should be returned if the identifiers are otherwise valid to prevent API consumers correlating different identifiers with a given end user. + + allOf: + - $ref: "#/components/schemas/Device" + - maxProperties: 1 + + PhoneNumber: + description: A public identifier addressing a telephone subscription. In mobile networks it corresponds to the MSISDN (Mobile Station International Subscriber Directory Number). In order to be globally unique it has to be formatted in international format, according to E.164 standard, prefixed with '+'. + type: string + pattern: '^\+[1-9][0-9]{4,14}$' + example: "+123456789" + + NetworkAccessIdentifier: + description: A public identifier addressing a subscription in a mobile network. In 3GPP terminology, it corresponds to the GPSI formatted with the External Identifier ({Local Identifier}@{Domain Identifier}). Unlike the telephone number, the network access identifier is not subjected to portability ruling in force, and is individually managed by each operator. + type: string + example: "123456789@example.com" + + DeviceIpv4Addr: + type: object + description: | + The device should be identified by either the public (observed) IP address and port as seen by the application server, or the private (local) and any public (observed) IP addresses in use by the device (this information can be obtained by various means, for example from some DNS servers). + + If the allocated and observed IP addresses are the same (i.e. NAT is not in use) then the same address should be specified for both publicAddress and privateAddress. + + If NAT64 is in use, the device should be identified by its publicAddress and publicPort, or separately by its allocated IPv6 address (field ipv6Address of the Device object) + + In all cases, publicAddress must be specified, along with at least one of either privateAddress or publicPort, dependent upon which is known. In general, mobile devices cannot be identified by their public IPv4 address alone. + properties: + publicAddress: + $ref: "#/components/schemas/SingleIpv4Addr" + privateAddress: + $ref: "#/components/schemas/SingleIpv4Addr" + publicPort: + $ref: "#/components/schemas/Port" + anyOf: + - required: [publicAddress, privateAddress] + - required: [publicAddress, publicPort] + example: + publicAddress: "84.125.93.10" + publicPort: 59765 + + SingleIpv4Addr: + description: A single IPv4 address with no subnet mask + type: string + format: ipv4 + example: "84.125.93.10" + + Port: + description: TCP or UDP port number + type: integer + minimum: 0 + maximum: 65535 + + DeviceIpv6Address: + description: | + The device should be identified by the observed IPv6 address, or by any single IPv6 address from within the subnet allocated to the device (e.g. adding ::0 to the /64 prefix). + type: string + format: ipv6 + example: 2001:db8:85a3:8d3:1319:8a2e:370:7344 + + Area: + description: Base schema for all areas + type: object + properties: + areaType: + $ref: "#/components/schemas/AreaType" + required: + - areaType + discriminator: + propertyName: areaType + mapping: + CIRCLE: "#/components/schemas/Circle" + POLYGON: "#/components/schemas/Polygon" + + AreaType: + type: string + description: | + Type of this area. + CIRCLE - The area is defined as a circle. + POLYGON - The area is defined as a polygon. + enum: + - CIRCLE + - POLYGON + + Circle: + description: Circular area + allOf: + - $ref: "#/components/schemas/Area" + - type: object + required: + - center + - radius + properties: + center: + $ref: "#/components/schemas/Point" + radius: + type: number + description: Distance from the center in meters + minimum: 1 + + Polygon: + description: Polygonal area. The Polygon should be a simple polygon, i.e. should not intersect itself. + allOf: + - $ref: "#/components/schemas/Area" + - type: object + required: + - boundary + properties: + boundary: + $ref: "#/components/schemas/PointList" + + PointList: + description: List of points defining a polygon + type: array + items: + $ref: "#/components/schemas/Point" + minItems: 3 + maxItems: 15 + + Point: + type: object + description: Coordinates (latitude, longitude) defining a location in a map + required: + - latitude + - longitude + properties: + latitude: + $ref: "#/components/schemas/Latitude" + longitude: + $ref: "#/components/schemas/Longitude" + example: + latitude: 50.735851 + longitude: 7.10066 + + Latitude: + description: Latitude component of a location + type: number + format: double + minimum: -90 + maximum: 90 + + Longitude: + description: Longitude component of location + type: number + format: double + minimum: -180 + maximum: 180 + + responses: + ####################################################### + ####################################################### + # ERROR RESPONSE SCHEMA TEMPLATE + # - Objective: Make normative error `status` and `code` values + # - Schema Template rationale: + # - The `allOf` in content.application/json.schema allows a combination of both the generic ErrorInfo schema and the specific schema for this error response, + # which validates that `status` and `code` have only the specified values. + # This `allOf` is used without discriminator because it does not imply any hierarchy between the models, just 2 schemas that must be independently validated. + ####################################################### + # ErrorResponseSchema: + # ... + # content: + # application/json: + # schema: + # allOf: + # - $ref: '#/components/schemas/ErrorInfo' + # - type: object + # properties: + # status: + # enum: + # - + # code: + # enum: + # - + # - + # examples: + # ExampleKey1: + # value: + # status: + # code: + # message: + # ExampleKey2: + # value: + # status: + # code: + # message: + ####################################################### + ####################################################### + Generic400: + description: Bad Request + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + allOf: + - $ref: "#/components/schemas/ErrorInfo" + - type: object + properties: + status: + enum: + - 400 + code: + enum: + - INVALID_ARGUMENT + - OUT_OF_RANGE + examples: + GENERIC_400_INVALID_ARGUMENT: + description: Invalid Argument. Generic Syntax Exception + value: + status: 400 + code: INVALID_ARGUMENT + message: Client specified an invalid argument, request body or query param. + GENERIC_400_OUT_OF_RANGE: + description: Out of Range. Specific Syntax Exception used when a given field has a pre-defined range or a invalid filter criteria combination is requested + value: + status: 400 + code: OUT_OF_RANGE + message: Client specified an invalid range. + Generic401: + description: Unauthorized + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + allOf: + - $ref: "#/components/schemas/ErrorInfo" + - type: object + properties: + status: + enum: + - 401 + code: + enum: + - UNAUTHENTICATED + examples: + GENERIC_401_UNAUTHENTICATED: + description: Request cannot be authenticated and a new authentication is required + value: + status: 401 + code: UNAUTHENTICATED + message: Request not authenticated due to missing, invalid, or expired credentials. A new authentication is required. + Generic403: + description: Forbidden + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + allOf: + - $ref: "#/components/schemas/ErrorInfo" + - type: object + properties: + status: + enum: + - 403 + code: + enum: + - PERMISSION_DENIED + - INVALID_TOKEN_CONTEXT + examples: + GENERIC_403_PERMISSION_DENIED: + description: Permission denied. OAuth2 token access does not have the required scope or when the user fails operational security + value: + status: 403 + code: PERMISSION_DENIED + message: Client does not have sufficient permissions to perform this action. + GENERIC_403_INVALID_TOKEN_CONTEXT: + description: Reflect some inconsistency between information in some field of the API and the related OAuth2 Token + value: + status: 403 + code: INVALID_TOKEN_CONTEXT + message: "{{field}} is not consistent with access token." + Generic404: + description: Not found + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + allOf: + - $ref: "#/components/schemas/ErrorInfo" + - type: object + properties: + status: + enum: + - 404 + code: + enum: + - NOT_FOUND + - IDENTIFIER_NOT_FOUND + examples: + GENERIC_404_NOT_FOUND: + description: Resource is not found + value: + status: 404 + code: NOT_FOUND + message: The specified resource is not found. + GENERIC_404_IDENTIFIER_NOT_FOUND: + description: Some identifier cannot be matched to a device + value: + status: 404 + code: IDENTIFIER_NOT_FOUND + message: Device identifier not found. + Generic405: + description: Method Not Allowed + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + allOf: + - $ref: "#/components/schemas/ErrorInfo" + - type: object + properties: + status: + enum: + - 405 + code: + enum: + - METHOD_NOT_ALLOWED + examples: + GENERIC_405_METHOD_NOT_ALLOWED: + description: Invalid HTTP verb used with a given endpoint + value: + status: 405 + code: METHOD_NOT_ALLOWED + message: The requested method is not allowed/supported on the target resource. + Generic406: + description: Not Acceptable + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + allOf: + - $ref: "#/components/schemas/ErrorInfo" + - type: object + properties: + status: + enum: + - 406 + code: + enum: + - NOT_ACCEPTABLE + examples: + GENERIC_406_NOT_ACCEPTABLE: + description: API Server does not accept the media type (`Accept-*` header) indicated by API client + value: + status: 406 + code: NOT_ACCEPTABLE + message: The server cannot produce a response matching the content requested by the client through `Accept-*` headers. + Generic409: + description: Conflict + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + allOf: + - $ref: "#/components/schemas/ErrorInfo" + - type: object + properties: + status: + enum: + - 409 + code: + enum: + - ABORTED + - ALREADY_EXISTS + - CONFLICT + examples: + GENERIC_409_ABORTED: + description: Concurreny of processes of the same nature/scope + value: + status: 409 + code: ABORTED + message: Concurrency conflict. + GENERIC_409_ALREADY_EXISTS: + description: Trying to create an existing resource + value: + status: 409 + code: ALREADY_EXISTS + message: The resource that a client tried to create already exists. + GENERIC_409_CONFLICT: + description: Duplication of an existing resource + value: + status: 409 + code: CONFLICT + message: A specified resource duplicate entry found. + Generic410: + description: Gone + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + allOf: + - $ref: "#/components/schemas/ErrorInfo" + - type: object + properties: + status: + enum: + - 410 + code: + enum: + - GONE + examples: + GENERIC_410_GONE: + description: Use in notifications flow to allow API Consumer to indicate that its callback is no longer available + value: + status: 410 + code: GONE + message: Access to the target resource is no longer available. + Generic412: + description: Failed precondition + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + allOf: + - $ref: "#/components/schemas/ErrorInfo" + - type: object + properties: + status: + enum: + - 412 + code: + enum: + - FAILED_PRECONDITION + examples: + GENERIC_412_FAILED_PRECONDITION: + description: Indication by the API Server that the request cannot be processed in current system state + value: + status: 412 + code: FAILED_PRECONDITION + message: Request cannot be executed in the current system state. + Generic415: + description: Unsupported Media Type + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + allOf: + - $ref: "#/components/schemas/ErrorInfo" + - type: object + properties: + status: + enum: + - 415 + code: + enum: + - UNSUPPORTED_MEDIA_TYPE + examples: + GENERIC_415_UNSUPPORTED_MEDIA_TYPE: + description: Payload format of the request is in an unsupported format by the Server. Should not happen + value: + status: 415 + code: UNSUPPORTED_MEDIA_TYPE + message: The server refuses to accept the request because the payload format is in an unsupported format. + Generic422: + description: Unprocessable Content + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + allOf: + - $ref: "#/components/schemas/ErrorInfo" + - type: object + properties: + status: + enum: + - 422 + code: + enum: + - SERVICE_NOT_APPLICABLE + - MISSING_IDENTIFIER + - UNSUPPORTED_IDENTIFIER + - UNNECESSARY_IDENTIFIER + examples: + GENERIC_422_SERVICE_NOT_APPLICABLE: + description: Service not applicable for the provided identifier + value: + status: 422 + code: SERVICE_NOT_APPLICABLE + message: The service is not available for the provided identifier. + GENERIC_422_MISSING_IDENTIFIER: + description: An identifier is not included in the request and the device or phone number identification cannot be derived from the 3-legged access token + value: + status: 422 + code: MISSING_IDENTIFIER + message: The device cannot be identified. + GENERIC_422_UNSUPPORTED_IDENTIFIER: + description: None of the provided identifiers is supported by the implementation + value: + status: 422 + code: UNSUPPORTED_IDENTIFIER + message: The identifier provided is not supported. + GENERIC_422_UNNECESSARY_IDENTIFIER: + description: An explicit identifier is provided when a device or phone number has already been identified from the access token + value: + status: 422 + code: UNNECESSARY_IDENTIFIER + message: The device is already identified by the access token. + Generic429: + description: Too Many Requests + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + allOf: + - $ref: "#/components/schemas/ErrorInfo" + - type: object + properties: + status: + enum: + - 429 + code: + enum: + - QUOTA_EXCEEDED + - TOO_MANY_REQUESTS + examples: + GENERIC_429_QUOTA_EXCEEDED: + description: Request is rejected due to exceeding a business quota limit + value: + status: 429 + code: QUOTA_EXCEEDED + message: Out of resource quota. + GENERIC_429_TOO_MANY_REQUESTS: + description: Access to the API has been temporarily blocked due to rate or spike arrest limits being reached + value: + status: 429 + code: TOO_MANY_REQUESTS + message: Rate limit reached. + Generic500: + description: Internal Server Error + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + allOf: + - $ref: "#/components/schemas/ErrorInfo" + - type: object + properties: + status: + enum: + - 500 + code: + enum: + - INTERNAL + examples: + GENERIC_500_INTERNAL: + description: Problem in Server side. Regular Server Exception + value: + status: 500 + code: INTERNAL + message: Unknown server error. Typically a server bug. + Generic501: + description: Not Implemented + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + allOf: + - $ref: "#/components/schemas/ErrorInfo" + - type: object + properties: + status: + enum: + - 501 + code: + enum: + - NOT_IMPLEMENTED + examples: + GENERIC_501_NOT_IMPLEMENTED: + description: Service not implemented. The use of this code should be avoided as far as possible to get the objective to reach aligned implementations + value: + status: 501 + code: NOT_IMPLEMENTED + message: This functionality is not implemented yet. + Generic502: + description: Bad Gateway + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + allOf: + - $ref: "#/components/schemas/ErrorInfo" + - type: object + properties: + status: + enum: + - 502 + code: + enum: + - BAD_GATEWAY + examples: + GENERIC_502_BAD_GATEWAY: + description: Internal routing problem in the Server side that blocks to manage the service properly + value: + status: 502 + code: BAD_GATEWAY + message: An upstream internal service cannot be reached. + Generic503: + description: Service Unavailable + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + allOf: + - $ref: "#/components/schemas/ErrorInfo" + - type: object + properties: + status: + enum: + - 503 + code: + enum: + - UNAVAILABLE + examples: + GENERIC_503_UNAVAILABLE: + description: Service is not available. Temporary situation usually related to maintenance process in the server side + value: + status: 503 + code: UNAVAILABLE + message: Service Unavailable. + Generic504: + description: Gateway Timeout + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + allOf: + - $ref: "#/components/schemas/ErrorInfo" + - type: object + properties: + status: + enum: + - 504 + code: + enum: + - TIMEOUT + examples: + GENERIC_504_TIMEOUT: + description: API Server Timeout + value: + status: 504 + code: TIMEOUT + message: Request timeout exceeded. diff --git a/code/API_definitions/Domain/Capabilities.yaml b/code/API_definitions/Domain/Capabilities.yaml index 1dc3ac6..94cb3ad 100644 --- a/code/API_definitions/Domain/Capabilities.yaml +++ b/code/API_definitions/Domain/Capabilities.yaml @@ -1,8 +1,20 @@ components: + parameters: + deviceId: + name: deviceId + in: path + description: | + The unique identifier of a Device. If the device exists but the caller lacks permission to access it, the API returns 403. + + Must be a valid UUID as defined by RFC 4122 (versions 1-5) using only lowercase hexadecimal characters. + required: true + schema: + $ref: "./NAM_Common.yaml#/components/schemas/UUID" + schemas: title: Operator Device Capabilities DeviceId: - $ref: "./Common.yaml#/components/schemas/DeviceId" + $ref: "./NAM_Common.yaml#/components/schemas/DeviceId" DeviceCapabilities: oneOf: diff --git a/code/API_definitions/Domain/Common.yaml b/code/API_definitions/Domain/Common.yaml deleted file mode 100644 index d28bf6c..0000000 --- a/code/API_definitions/Domain/Common.yaml +++ /dev/null @@ -1,18 +0,0 @@ -# OpenAPI Specification for Common Definitions -components: - parameters: - deviceIdParam: - name: deviceId - in: path - required: true - schema: - $ref: "#/components/schemas/DeviceId" - description: ID of the device to retrieve capabilities for - - schemas: - DeviceId: - type: string - minLength: 1 - maxLength: 64 - description: The unique identifier for a device - example: device-1 diff --git a/code/API_definitions/Domain/NAM_Common.yaml b/code/API_definitions/Domain/NAM_Common.yaml new file mode 100644 index 0000000..14041f9 --- /dev/null +++ b/code/API_definitions/Domain/NAM_Common.yaml @@ -0,0 +1,228 @@ +# OpenAPI Specification for Common Definitions +components: + + securitySchemes: # Using this over CAMARA_common.yaml in order to add description + openId: + type: openIdConnect + description: | + OpenID Connect authentication with scope-based authorization. + + **Resource Isolation:** + Unless otherwise specified, all scopes only grant access to resources + (e.g., Trust Domains, Reboot Requests) created by the same API client. + API clients cannot access or modify resources created by other API clients + unless the `:read-all` or `:admin` scope variants are explicitly granted. + + **Scope Model:** + This API uses a simplified scope model to balance clarity with flexibility. + Functional authorization (e.g., managing Trust Domains) is handled by scopes, + while ownership enforcement is handled by the API provider. + + **Available Scopes:** + - `network-access-management:trust-domains` — Full management of Trust Domains created by the calling API client + (includes create, read, modify, and delete actions). + - `network-access-management:trust-domains:read-all` — Read-only access to all Trust Domains + associated with the same subscriber, including those created by other API clients. + Intended for use cases involving federated discovery or configuration replication. + - `network-access-management:reboot` — Create, list, and manage Reboot Requests for network + access devices owned by or delegated to the calling API client. + openIdConnectUrl: https://example.com/.well-known/openid-configuration + + 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" + + PropertyAddress: + type: object + description: Represents a physical property address following TMF673 Geographic Address Management API specification. + 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 + + ResourceIdentifier: + type: object + properties: + id: + allOf: + - $ref: "#/components/schemas/UUID" + readOnly: true + required: + - id + description: A generic schema for resources identified by a unique ID. + + ResourceAudit: # Generic reusable unique resource schema + type: object + properties: + createdAt: + allOf: + - $ref: "#/components/schemas/DateTime" + - description: | + The creation date and time of the trust domain. 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). + - readOnly: true + createdBy: + allOf: + - $ref: "#/components/schemas/UUID" + description: | + The ID of the user or system that created this resource. + example: "550e8400-e29b-41d4-a716-446655440000" + readOnly: true + modifiedAt: + allOf: + - $ref: "#/components/schemas/DateTime" + - description: | + The last update date and time of the trust domain. 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). + - readOnly: true + modifiedBy: + allOf: + - $ref: "#/components/schemas/UUID" + description: | + The ID of the user or system that modified this resource. + example: "660e8400-e29b-41d4-a716-446655440000" + readOnly: true + description: A generic schema for resources with unique identifiers and audit fields. + + UUID: + type: string + format: uuid + pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$' + minLength: 36 + maxLength: 36 + description: | + A universally unique identifier (UUID) as defined by RFC 4122. + Must be a valid UUID format with proper version (1-5) and variant bits. + Only lowercase hexadecimal characters are accepted for consistency. + example: "550e8400-e29b-41d4-a716-446655440000" diff --git a/code/API_definitions/Domain/NetworkAccessDevices/NetworkAccessDevices.yaml b/code/API_definitions/Domain/NetworkAccessDevices/NetworkAccessDevices.yaml new file mode 100644 index 0000000..5caa752 --- /dev/null +++ b/code/API_definitions/Domain/NetworkAccessDevices/NetworkAccessDevices.yaml @@ -0,0 +1,128 @@ +# Local anchor definitions for external component examples. There isn't a native OpenAPI way to +# cross-reference examples across files, so we define them here for reuse. +_imported_examples: + uuid-example: &uuid-example "3fa85f64-5717-4562-b3fc-2c963f66afa6" + uuid-example-2: &uuid-example-2 "123e4567-e89b-12d3-a456-426614174000" + property-address-example: &property-address-example + id: *uuid-example + addressLine1: "123 Main St" + addressLine2: "Suite 456" + streetNr: "123" + streetNrSuffix: "A" + streetNrLast: "125" + streetNrLastSuffix: "B" + streetName: "Main" + subUnitType: "Apartment" + subUnitNr: "A12" + levelType: "Floor" + levelNr: "3" + buildingName: "Sunset Towers" + privateStreetName: "Private Rd" + locality: "Example Locality" + city: "Example State" + stateOrProvince: "EX" + country: "United States" + postCode: "12345" + postCodeExtension: "6789" + service-site-example: &service-site-example + id: "3fa85f64-5717-4562-b3fc-2c963f66afa6" + name: "Primary Residence" + description: "123 Main Street" + location: *property-address-example + + +components: + parameters: + networkAccessDeviceId: + name: networkAccessDeviceId + in: path + description: | + The unique identifier of the Network Access Device. If the device exists but the caller lacks permission to access it, the API returns 403. + + Must be a valid UUID as defined by RFC 4122 (versions 1-5) using only lowercase hexadecimal characters. + required: true + schema: + $ref: "../NAM_Common.yaml#/components/schemas/UUID" + schemas: + NetworkAccessDevice: + description: | + Represents a network access device managed within the network access management system. + This schema represents operator-supplied network access equipment (e.g., gateways, mesh Wi-Fi systems). + It extends the Commonalities Device model but MUST NOT be confused with end-user devices. + The identifiers and addressing fields reflect the operator-managed equipment, not client equipment. + allOf: + - $ref: "../NAM_Common.yaml#/components/schemas/ResourceIdentifier" + - $ref: "../CAMARA_common.yaml#/components/schemas/Device" + - type: object + properties: + id: + readOnly: true + 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: "../Services/ServiceSites.yaml#/components/schemas/ServiceSite" + deviceStatus: + type: string + enum: + - connected + - disconnected + - unavailable + default: unavailable + description: The current status of the device + example: &device-status "connected" + required: + - id + example: &device + id: *uuid-example + deviceStatus: *device-status + name: *device-name + description: *device-description + hardwareAddress: *device-hardware-address + serviceSite: *service-site-example + + NetworkAccessDeviceList: + type: array + description: A list of network access devices. + items: + $ref: "#/components/schemas/NetworkAccessDevice" + example: &device-list + - *device + - id: *uuid-example-2 + deviceStatus: "disconnected" + name: "Gateway-2" + description: "Another Wi-Fi gateway device" + hardwareAddress: &device-hardware-address2 + hardwareAddressType: "EUI-48" + value: "AB:CD:EF:12:34:56" + serviceSite: *service-site-example diff --git a/code/API_definitions/Domain/Policy.yaml b/code/API_definitions/Domain/Policy.yaml new file mode 100644 index 0000000..e480227 --- /dev/null +++ b/code/API_definitions/Domain/Policy.yaml @@ -0,0 +1,82 @@ +# This file defines the Policies schema model that describe the various policies applicable to +# Trust Domains. +components: + schemas: + + Policies: + type: object + description: A set of policies governing Trust Domain behavior. Omission of a policy indicates no constraint for that category. Policies are applied independently unless otherwise specified by the implementation. + properties: + maxDevices: + $ref: '#/components/schemas/MaxDevicesPolicy' + maxDomainDownstreamRate: + $ref: '#/components/schemas/MaxDomainDownstreamRatePolicy' + maxDomainUpstreamRate: + $ref: '#/components/schemas/MaxDomainUpstreamRatePolicy' + egressAllowedList: + $ref: '#/components/schemas/EgressAllowedListPolicy' + additionalProperties: false + example: + maxDevices: 10 + maxDomainDownstreamRate: + value: 500000 + unit: Kbps + maxDomainUpstreamRate: + value: 10000 + unit: Kbps + egressAllowedList: + - "api.vendor.com" + - "updates.vendor.com" + + MaxDevicesPolicy: + type: integer + minimum: 1 + description: Limits the number of devices that may join the Trust Domain. + example: 10 + + MaxDomainDownstreamRatePolicy: + type: object + properties: + value: + type: integer + description: Maximum downstream throughput across the domain. + unit: + type: string + enum: [Kbps, Mbps, Gbps] + description: Unit of measurement for downstream throughput. + required: + - value + - unit + description: Maximum downstream throughput policy across the Trust Domain. + example: + value: 1000000 + unit: Kbps + + MaxDomainUpstreamRatePolicy: + type: object + properties: + value: + type: integer + description: Maximum upstream throughput across the domain. + unit: + type: string + enum: [Kbps, Mbps, Gbps] + description: Unit of measurement for upstream throughput. + required: + - value + - unit + description: Maximum upstream throughput policy across the Trust Domain. + example: + value: 500000 + unit: Kbps + + EgressAllowedListPolicy: + type: array + items: + type: string + description: FQDN or CIDR pattern + minItems: 1 + description: Restricts egress traffic to the specified destinations. + example: + - "api.vendor.com" + - "updates.vendor.com" diff --git a/code/API_definitions/Domain/RebootRequests/RebootRequests.yaml b/code/API_definitions/Domain/RebootRequests/RebootRequests.yaml new file mode 100644 index 0000000..9574e79 --- /dev/null +++ b/code/API_definitions/Domain/RebootRequests/RebootRequests.yaml @@ -0,0 +1,120 @@ +# Local anchor definitions for external component examples. There isn't a native OpenAPI way to +# cross-reference examples across files, so we define them here for reuse. +_imported_examples: + uuid-example: &uuid-example-1 "3fa85f64-5717-4562-b3fc-2c963f66afa6" + uuid-example-2: &uuid-example-2 "123e4567-e89b-12d3-a456-426614174000" + date-time: &date-time "2023-07-03T12:27:08.312Z" + device-uuid-1: &device-uuid-1 "934ee3f4-1234-5678-9abc-abcdef123456" + device-uuid-2: &device-uuid-2 "454ee3f4-1234-5678-9abc-abcdef123456" + device-id-list: &device-id-list + - *device-uuid-1 + - *device-uuid-2 + created-by-example: &created-by-example "550e8400-e29b-41d4-a716-446655440000" + modified-by-example: &modified-by-example "660e8400-e29b-41d4-a716-446655440000" +components: + + parameters: + rebootRequestId: + name: rebootRequestId + in: path + required: true + schema: + $ref: "../NAM_Common.yaml#/components/schemas/UUID" + description: ID of the Reboot Request. If the Reboot Request exists but the caller lacks permission to access it, the API returns 403. + + schemas: + RebootRequestUpdate: + type: object + description: Represents updatable fields for a reboot request, including optional message and scheduling information. + properties: + message: + type: string + maxLength: 255 + description: A message related to the reboot request + example: &reboot-message "reboot to correct performance" + atTime: + allOf: + - $ref: "../NAM_Common.yaml#/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). + + RebootRequestCreate: + description: Represents the creation of a reboot request, including target devices and optional scheduling. If devices is omitted, the provider MAY infer a default device. Inference rules vary by implementation. If inference is unsupported or ambiguous, creation MUST fail. + allOf: + - $ref: "#/components/schemas/RebootRequestUpdate" + - properties: + devices: + type: array + items: + $ref: "../NAM_Common.yaml#/components/schemas/UUID" + 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 + + RebootRequest: + allOf: + - $ref: "../NAM_Common.yaml#/components/schemas/ResourceIdentifier" + - $ref: "#/components/schemas/RebootRequestCreate" + - $ref: "../NAM_Common.yaml#/components/schemas/ResourceAudit" + - type: object + properties: + id: + readOnly: true + createdAt: + readOnly: true + createdBy: + readOnly: true + modifiedAt: + readOnly: true + modifiedBy: + readOnly: true + required: + - devices + description: Represents a reboot request for one or more network access devices. + + RebootRequestList: + type: array + items: + $ref: "#/components/schemas/RebootRequest" + + examples: + RebootRequestCreateImmediateDefaultDevice: + summary: Example of a Reboot Request for immediate reboot + value: + message: "reboot to correct performance" + + RebootRequestCreateScheduledMultipleDevices: + summary: Example of a Reboot Request for scheduled reboot of multiple devices + value: + message: "Scheduled reboot for maintenance" + atTime: *date-time + devices: *device-id-list + + RebootRequestResponseInferred: + summary: Response after inferred default device reboot request + value: + id: *uuid-example-1 + message: "reboot to correct performance" + devices: + - *device-uuid-1 + atTime: *date-time + createdAt: *date-time + createdBy: *created-by-example + modifiedAt: *date-time + modifiedBy: *modified-by-example + + RebootRequestResponseExplicit: + summary: Response after explicit multi-device reboot request + value: + id: *uuid-example-2 + message: "scheduled maintenance reboot" + devices: *device-id-list + atTime: *date-time + createdAt: *date-time + createdBy: *created-by-example + modifiedAt: *date-time + modifiedBy: *modified-by-example diff --git a/code/API_definitions/Domain/Services/ServiceSites.yaml b/code/API_definitions/Domain/Services/ServiceSites.yaml new file mode 100644 index 0000000..37d32c2 --- /dev/null +++ b/code/API_definitions/Domain/Services/ServiceSites.yaml @@ -0,0 +1,67 @@ +# Local anchor definitions for external component examples. There isn't a native OpenAPI way to +# cross-reference examples across files, so we define them here for reuse. +_imported_examples: + uuid-example: &uuid-example "3fa85f64-5717-4562-b3fc-2c963f66afa6" + uuid-example-2: &uuid-example-2 "123e4567-e89b-12d3-a456-426614174000" + property-address-example: &property-address-example + id: *uuid-example + addressLine1: "123 Main St" + addressLine2: "Suite 456" + streetNr: "123" + streetNrSuffix: "A" + streetNrLast: "125" + streetNrLastSuffix: "B" + streetName: "Main" + subUnitType: "Apartment" + subUnitNr: "A12" + levelType: "Floor" + levelNr: "3" + buildingName: "Sunset Towers" + privateStreetName: "Private Rd" + locality: "Example Locality" + city: "Example State" + stateOrProvince: "EX" + country: "United States" + postCode: "12345" + postCodeExtension: "6789" + +components: + schemas: + ServiceSite: + type: object + description: A Service Site represents a subscriber location associated with one or more Network Access Devices. Implementations MAY provide geographic coordinates, postal address data, or both, depending on local regulatory and operational requirements. + properties: + id: + allOf: + - $ref: "../NAM_Common.yaml#/components/schemas/UUID" + readOnly: true + name: + type: string + description: The name of the service site. + maxLength: 64 + example: &service-site-name "Example Service Site 1" + description: + type: string + description: A textual description of the service site. + maxLength: 64 + example: &service-site-description "This is the first example service site" + location: + type: object + description: Geographic location information for the service site, including coordinates and/or property address. + properties: + geographicPoint: + $ref: "../CAMARA_common.yaml#/components/schemas/Point" + propertyAddress: + $ref: "../NAM_Common.yaml#/components/schemas/PropertyAddress" + example: &service-site-location + geographicPoint: + latitude: 50.735851 + longitude: 7.10066 + propertyAddress: *property-address-example + required: + - id + example: &service-site + id: *uuid-example + name: *service-site-name + description: *service-site-description + location: *service-site-location diff --git a/code/API_definitions/Domain/Services/Services.yaml b/code/API_definitions/Domain/Services/Services.yaml new file mode 100644 index 0000000..303ea9d --- /dev/null +++ b/code/API_definitions/Domain/Services/Services.yaml @@ -0,0 +1,101 @@ +# Local anchor definitions for external component examples. There isn't a native OpenAPI way to +# cross-reference examples across files, so we define them here for reuse. +_imported_examples: + uuid-example: &uuid-example "3fa85f64-5717-4562-b3fc-2c963f66afa6" + uuid-example-2: &uuid-example-2 "123e4567-e89b-12d3-a456-426614174000" + uuid-example-3: &uuid-example-3 "123e4567-e89b-12d3-a456-426614174001" + property-address-example: &property-address-example + id: *uuid-example + addressLine1: "123 Main St" + addressLine2: "Suite 456" + streetNr: "123" + streetNrSuffix: "A" + streetNrLast: "125" + streetNrLastSuffix: "B" + streetName: "Main" + subUnitType: "Apartment" + subUnitNr: "A12" + levelType: "Floor" + levelNr: "3" + buildingName: "Sunset Towers" + privateStreetName: "Private Rd" + locality: "Example Locality" + city: "Example State" + stateOrProvince: "EX" + country: "United States" + postCode: "12345" + postCodeExtension: "6789" + service-site-example: &service-site-example + id: "3fa85f64-5717-4562-b3fc-2c963f66afa6" + name: "Primary Residence" + description: "123 Main Street" + location: *property-address-example + +components: + parameters: + serviceId: + name: serviceId + in: path + description: The unique identifier of the Service. If the service exists but the caller lacks permission to access it, the API returns 403. + required: true + schema: + $ref: "#/components/schemas/ServiceId" + + schemas: + ServiceId: + allOf: + - $ref: "../NAM_Common.yaml#/components/schemas/UUID" + description: | + A unique identifier that represents a service account associated with this resource. + + Must be a valid UUID as defined by RFC 4122 (versions 1-5) using only lowercase hexadecimal characters. + + Service: + type: object + description: | + A service represents a logical commercial subscription or account relationship + between a network operator and a subscriber. This may correspond to residential, + commercial, public Wi-Fi, or other service types. + properties: + id: + $ref: "#/components/schemas/ServiceId" + name: + type: string + maxLength: 64 + description: Optional friendly name for the service + example: "Main Home Internet" + description: + type: string + maxLength: 255 + description: Optional description of the service + example: "Internet subscription for primary residence" + serviceSite: + # Optional. Present for location-specific services (e.g., residential, office), absent for general services (e.g., public Wi-Fi) + $ref: "./ServiceSites.yaml#/components/schemas/ServiceSite" + required: + - id + example: + id: *uuid-example + name: "Main Home Internet" + description: "Internet subscription for primary residence" + serviceSite: + id: *uuid-example-2 + name: "Primary Residence" + description: "123 Main Street" + + ServiceList: + type: array + description: A list of services accessible to the calling identity + items: + $ref: "#/components/schemas/Service" + example: + - id: *uuid-example + name: "Main Home Internet" + description: "Internet subscription for primary residence" + serviceSite: + id: *uuid-example-2 + name: "Primary Residence" + description: "123 Main Street" + - id: *uuid-example-3 + name: "Vacation Home Internet" + description: "Internet subscription for vacation home" diff --git a/code/API_definitions/Domain/TrustDomains/TrustDomainCapabilities.yaml b/code/API_definitions/Domain/TrustDomains/TrustDomainCapabilities.yaml new file mode 100644 index 0000000..9b53e79 --- /dev/null +++ b/code/API_definitions/Domain/TrustDomains/TrustDomainCapabilities.yaml @@ -0,0 +1,280 @@ +components: + schemas: + TrustDomainCapabilities: + type: object + properties: + supportedAccessTypes: + type: array + description: List of supported access types and their variants + items: + $ref: "#/components/schemas/SupportedAccessType" + minItems: 1 + supportedPolicies: + type: object + description: Map of supported policy types to their capability details + properties: + maxDevices: + $ref: "#/components/schemas/MaxDevicesPolicyCapability" + maxDomainDownstreamRate: + $ref: "#/components/schemas/BandwidthPolicyCapability" + maxDomainUpstreamRate: + $ref: "#/components/schemas/BandwidthPolicyCapability" + egressAllowedList: + $ref: "#/components/schemas/EgressPolicyCapability" + example: + maxDevices: + maxValue: 100 + minValue: 1 + maxDomainDownstreamRate: + maxValue: 1000000000 + minValue: 1000000 + required: + - supportedAccessTypes + description: Describes the Trust Domain configuration capabilities supported by this API provider + + SupportedAccessType: + type: object + description: Access type capabilities with discriminated properties based on accessType. Represents the configuration options supported by the API provider for a given access type. This is distinct from AccessDetail, which represents the configuration requested by an API client. + properties: + accessType: + type: string + enum: + - "Wi-Fi:WPA_PERSONAL" + - "Wi-Fi:WPA_ENTERPRISE" + - "Thread:STRUCTURED" + - "Thread:TLV" + description: The supported access type identifier (must match POST endpoint values) + oneOf: + - $ref: "#/components/schemas/SupportedWiFiWpaPersonalAccessType" + - $ref: "#/components/schemas/SupportedWiFiWpaEnterpriseAccessType" + - $ref: "#/components/schemas/SupportedThreadStructuredAccessType" + - $ref: "#/components/schemas/SupportedThreadTlvAccessType" + discriminator: + propertyName: accessType + mapping: + "Wi-Fi:WPA_PERSONAL": "#/components/schemas/SupportedWiFiWpaPersonalAccessType" + "Wi-Fi:WPA_ENTERPRISE": "#/components/schemas/SupportedWiFiWpaEnterpriseAccessType" + "Thread:STRUCTURED": "#/components/schemas/SupportedThreadStructuredAccessType" + "Thread:TLV": "#/components/schemas/SupportedThreadTlvAccessType" + required: + - accessType + + SupportedWiFiWpaPersonalAccessType: + type: object + properties: + accessType: + type: string + description: The type of network access. + enum: + - "Wi-Fi:WPA_PERSONAL" + example: "Wi-Fi:WPA_PERSONAL" + wifiProperties: + $ref: "#/components/schemas/WiFiAccessTypeProperties" + required: + - accessType + - wifiProperties + description: Wi-Fi WPA Personal access type capabilities + + SupportedWiFiWpaEnterpriseAccessType: + type: object + properties: + accessType: + type: string + description: The type of network access. + enum: + - "Wi-Fi:WPA_ENTERPRISE" + example: "Wi-Fi:WPA_ENTERPRISE" + wifiProperties: + $ref: "#/components/schemas/WiFiAccessTypeProperties" + required: + - accessType + - wifiProperties + description: Wi-Fi WPA Enterprise access type capabilities + + SupportedThreadStructuredAccessType: + type: object + properties: + accessType: + type: string + description: The type of network access. + enum: + - "Thread:STRUCTURED" + example: "Thread:STRUCTURED" + threadProperties: + $ref: "#/components/schemas/ThreadAccessTypeProperties" + required: + - accessType + - threadProperties + description: Thread structured access type capabilities + + SupportedThreadTlvAccessType: + type: object + properties: + accessType: + type: string + description: The type of network access. + enum: + - "Thread:TLV" + example: "Thread:TLV" + threadProperties: + $ref: "#/components/schemas/ThreadAccessTypeProperties" + required: + - accessType + - threadProperties + description: Thread TLV access type capabilities + + # Explicit policy capability schemas + MaxDevicesPolicyCapability: + type: object + properties: + maxValue: + type: integer + minimum: 1 + description: Maximum number of devices allowed + example: 100 + minValue: + type: integer + minimum: 1 + description: Minimum number of devices allowed + example: 1 + required: + - maxValue + - minValue + description: Capabilities for maximum devices policy + + BandwidthPolicyCapability: + type: object + properties: + maxValue: + type: integer + minimum: 1 + description: Maximum bandwidth value in bits per second + example: 1000000000 + minValue: + type: integer + minimum: 1 + description: Minimum bandwidth value in bits per second + example: 1000000 + required: + - maxValue + - minValue + description: Capabilities for bandwidth control policies + + EgressPolicyCapability: + type: object + properties: + maxEntries: + type: integer + minimum: 1 + description: Maximum number of allowed egress destinations + example: 50 + supportedDestinationTypes: + type: array + items: + type: string + enum: ["IP", "FQDN", "CIDR"] + description: Supported destination address formats + example: ["IP", "FQDN", "CIDR"] + required: + - maxEntries + - supportedDestinationTypes + description: Capabilities for egress allowed list policy + + # Explicit access type property schemas + WiFiAccessTypeProperties: + type: object + properties: + ssidRequired: + type: boolean + description: Whether SSID must be provided (false if can be inferred) + example: true + supportedSecurityModes: + type: array + items: + type: string + enum: + - "WPA2-Personal" + - "WPA3-Personal" + - "WPA2-WPA3-Personal" + - "WPA2-Enterprise" + - "WPA3-Enterprise" + description: Supported Wi-Fi security mode types + example: ["WPA2-Personal", "WPA3-Personal"] + passwordConstraints: + $ref: "#/components/schemas/PasswordConstraints" + authServerRequired: + type: boolean + description: Whether authentication server must be specified for Enterprise modes + example: false + description: Wi-Fi specific access type properties + + ThreadAccessTypeProperties: + type: object + properties: + supportedChannels: + type: object + properties: + min: + type: integer + minimum: 11 + maximum: 26 + description: Minimum supported Thread channel + example: 11 + max: + type: integer + minimum: 11 + maximum: 26 + description: Maximum supported Thread channel + example: 26 + required: + - min + - max + description: Range of supported Thread channels + networkKeyFormat: + type: string + enum: ["32-hex-digits"] + description: Required format for Thread network keys + example: "32-hex-digits" + networkNameConstraints: + type: object + properties: + minLength: + type: integer + minimum: 1 + example: 1 + maxLength: + type: integer + minimum: 1 + example: 16 + required: + - minLength + - maxLength + description: Constraints on Thread network names + maxDatasetLength: + type: integer + minimum: 1 + description: Maximum length for TLV operational dataset (applies to Thread:TLV) + example: 255 + description: Thread specific access type properties + + PasswordConstraints: + type: object + properties: + minLength: + type: integer + minimum: 8 + description: Minimum password length + example: 8 + maxLength: + type: integer + minimum: 1 + description: Maximum password length + example: 63 + requireSpecialCharacters: + type: boolean + description: Whether special characters are required + example: false + required: + - minLength + - maxLength + description: Password validation constraints diff --git a/code/API_definitions/Domain/TrustDomains/TrustDomains.yaml b/code/API_definitions/Domain/TrustDomains/TrustDomains.yaml new file mode 100644 index 0000000..5d79a7b --- /dev/null +++ b/code/API_definitions/Domain/TrustDomains/TrustDomains.yaml @@ -0,0 +1,265 @@ +# Local anchor definitions for external component examples. There isn't a native OpenAPI way to +# cross-reference examples across files, so we define them here for reuse. +_imported_examples: + uuid-example: &uuid-example "3fa85f64-5717-4562-b3fc-2c963f66afa6" + service-uuid-example: &service-uuid-example "123e4567-e89b-12d3-a456-426614174000" + wifi-wpa2-personal-basic-example: &wifi-wpa2-personal-basic-example + accessType: "Wi-Fi:WPA_PERSONAL" + securityMode: + password: "my-password" + securityModeType: "WPA2-Personal" + + wifi-wpa2-personal-example: &wifi-wpa2-personal-example + accessType: "Wi-Fi:WPA_PERSONAL" + ssid: "my-ssid" + securityMode: + password: "my-password" + securityModeType: "WPA2-Personal" + + wifi-wpa3-personal-example: &wifi-wpa3-personal-example + accessType: "Wi-Fi:WPA_PERSONAL" + ssid: "my-ssid" + securityMode: + password: "my-password" + securityModeType: "WPA3-Personal" + + thread-structured-example: &thread-structured-example + accessType: "Thread:STRUCTURED" + channel: 13 + extendedPanId: "d63e8e3e495ebbc3" + networkKey: "dfd34f0f05cad978ec4e32b0413038ff" + networkName: "Spec-Thread-B3AF" + panId: "d63e" + + thread-tlv-example: &thread-tlv-example + accessType: "Thread:TLV" + mode: tlv + operationalDataset: "0e08000000000000010010000102030405060708090a0b0c0d0e0f" + + max-devices-policy-example: &max-devices-policy-example + maxDevices: 10 + + max-bandwidth-policy-example: &max-bandwidth-policy-example + maxDomainDownstreamRate: + value: 1000000 + unit: Kbps + maxDomainUpstreamRate: + value: 500000 + unit: Kbps + + egress-allowed-list-policy-example: &egress-allowed-list-policy-example + egressAllowedList: + - "api.vendor.com" + - "updates.vendor.com" + + created-by-example: &created-by-example "550e8400-e29b-41d4-a716-446655440000" + modified-by-example: &modified-by-example "660e8400-e29b-41d4-a716-446655440000" + modified-by-example-2: &modified-by-example-2 "770e8400-e29b-41d4-a716-446655440000" + +components: + + parameters: + trustDomainId: + name: trustDomainId + in: path + required: true + schema: + $ref: "../NAM_Common.yaml#/components/schemas/UUID" + description: ID of the Trust Domain. If the Trust Domain exists but the caller lacks permission to access it, the API returns 403. + + schemas: + + TrustDomainUpdate: + type: object + description: Represents the updatable fields of a trust domain within the network access management system. + properties: + name: + type: string + description: Human-readable name for the trust domain. + example: "Primary WiFi Network" + description: + type: string + description: Detailed description of the trust domain. + example: "Primary home WiFi Network for all devices" + enabled: + type: boolean + description: Indicates whether the trust domain is currently enabled. + example: true + expiration: + allOf: + - $ref: "../NAM_Common.yaml#/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). + + If omitted, the trust domain will not automatically expire. + policies: + $ref: "../Policy.yaml#/components/schemas/Policies" + accessDetails: + type: array + # Each item grants access for a device to this Trust Domain, scoped by the associated AP/network access device or AP group. + description: | + A list of access configurations that define how end-user devices may join the + Trust Domain. Each entry represents one access type (e.g., Wi-Fi WPA Personal, + Wi-Fi WPA Enterprise, Thread Structured, Thread TLV). + + **Multiplicity and Uniqueness** + - A Trust Domain MUST contain at least one accessDetail entry. + - Each `accessType` SHOULD appear at most once. If multiple entries of the same + `accessType` are provided, the API provider MAY reject the request. + - Order of entries has no semantic meaning. + + **Creation and Update Semantics** + - On creation (POST), the full list of accessDetails MUST be provided. + - On update (PATCH), the list replaces the previous list entirely when included. + Partial merge semantics are not defined; clients MUST supply the complete + desired configuration for this field. + - To remove all access types, clients MAY provide an empty array, although the + API provider MAY reject configurations that result in no valid admittance + method for the Trust Domain. + + **Validation Expectations** + - The API provider MUST validate that the requested access types and their + properties conform to the provider's advertised capabilities + (via GET /trust-domains/capabilities). + - Providers MAY enforce additional constraints (e.g., SSID uniqueness, + channel restrictions, Thread dataset rules) based on local policy. + + **Deployment Behavior** + - All Network Access Devices configured with this Trust Domain MUST apply all + supplied accessDetails entries, unless the provider's capabilities indicate + that certain access types are not supported on specific devices. + items: + $ref: "../AccessDetail.yaml#/components/schemas/AccessDetail" + minItems: 1 + + TrustDomainCreate: + allOf: + - $ref: "#/components/schemas/TrustDomainUpdate" + description: Represents the creation of a new trust domain within the network access management system. + required: + - name + - enabled + - accessDetails + - serviceId + properties: + serviceId: + $ref: "../Services/Services.yaml#/components/schemas/ServiceId" + + TrustDomain: + allOf: + - $ref: "../NAM_Common.yaml#/components/schemas/ResourceIdentifier" + - $ref: "#/components/schemas/TrustDomainCreate" + - $ref: "../NAM_Common.yaml#/components/schemas/ResourceAudit" + - type: object + properties: + id: + readOnly: true + createdAt: + readOnly: true + createdBy: + readOnly: true + modifiedAt: + readOnly: true + modifiedBy: + readOnly: true + description: Represents a trust domain within the network access management system. + + + examples: + + TrustDomainCreateWpa2Personal: + summary: Create a Trust Domain with WPA2-Personal Wi-Fi access. + value: + name: "Primary WiFi Network" + description: "Request defines a Trust Domain with WPA2-Personal Wi-Fi access. The request specifies an SSID, implying the SSID is created on the network infrastructure." + enabled: true + accessDetails: + - <<: *wifi-wpa2-personal-example + serviceId: *service-uuid-example + + TrustDomainCreateInferredSsid: + summary: Create a Trust Domain with inferred SSID Wi-Fi access. + value: + name: "Inferred SSID Network" + description: "Request defines a Trust Domain with inferred SSID Wi-Fi access. The request omits the SSID, implying the Trust Domain is applied to an existing SSID on the network infrastructure." + enabled: true + accessDetails: + - accessType: "Wi-Fi:WPA_PERSONAL" + securityMode: + password: "my-password" + securityModeType: "WPA2-Personal" + serviceId: *service-uuid-example + + TrustDomainCreateEphemeral: + summary: Create a Trust Domain with ephemeral access details. + value: + name: "Ephemeral Network" + description: "Request defines a Trust Domain with ephemeral access details." + enabled: true + accessDetails: + - <<: *wifi-wpa3-personal-example + expiration: "2024-12-31T23:59:59Z" + policies: + <<: *max-devices-policy-example + serviceId: *service-uuid-example + + TrustDomainCreateThreadStructured: + summary: Create a Trust Domain with Thread structured access details. + value: + name: "Thread Structured Network" + description: "Request defines a Trust Domain with Thread structured access details." + enabled: true + accessDetails: + - <<: *thread-structured-example + serviceId: *service-uuid-example + + TrustDomainCreateQoSPolicies: + summary: Create a Trust Domain with QoS policies. + value: + name: "QoS Policy Network" + description: "Request defines a Trust Domain with QoS policies." + enabled: true + accessDetails: + - <<: *wifi-wpa3-personal-example + policies: + <<: *max-bandwidth-policy-example + serviceId: *service-uuid-example + + ## Example responses + TrustDomainResponseBasic: + summary: Basic Trust Domain Response + description: Example of a created Trust Domain with minimal details. + value: + id: *uuid-example + name: "Basic Trust Domain" + description: "A basic trust domain example" + enabled: true + accessDetails: + - <<: *wifi-wpa2-personal-example + serviceId: *service-uuid-example + createdAt: "2025-10-21T14:27:08.312Z" + createdBy: *created-by-example + modifiedAt: "2025-10-21T14:27:08.312Z" + modifiedBy: *modified-by-example + + TrustDomainResponseWiFiThread: + summary: Created Trust Domain (Wi-Fi + Thread) + description: Example of a created Trust Domain including Wi-Fi and Thread access details and populated policies. + value: + id: *uuid-example + name: "Primary WiFi Network" + description: "Primary home Wi-Fi Network for all devices" + enabled: true + expiration: "2025-10-21T14:27:08.312Z" + policies: + <<: *egress-allowed-list-policy-example + accessDetails: + - <<: *wifi-wpa3-personal-example + - <<: *thread-structured-example + serviceId: *service-uuid-example + createdAt: "2025-10-21T14:27:08.312Z" + createdBy: *created-by-example + modifiedAt: "2025-10-21T14:27:08.312Z" + modifiedBy: *modified-by-example-2 diff --git a/code/API_definitions/README.md b/code/API_definitions/README.md new file mode 100644 index 0000000..9de44a7 --- /dev/null +++ b/code/API_definitions/README.md @@ -0,0 +1,202 @@ +# Network Access Management API Definitions + +This directory contains the OpenAPI specifications for the Network Access Management API, organized into modular components for better maintainability and reusability. + +## Overview + +The API definitions have been restructured from a monolithic approach to a modular, component-based architecture. This allows for better code reuse, easier maintenance, and cleaner separation of concerns. + +## Folder Structure + +``` +API_definitions/ +├── README.md # This file (authoring & process docs) +├── redocly.yaml # Lint/bundle configuration (Redocly CLI) +├── network-access-management.yaml # Primary entrypoint spec (generated from template) +├── Templates/ # Template specs used to produce bundled variants +│ ├── network-access-management-template.yaml # Source template assembled into the main NAM bundle +└── Domain/ # Modular domain-focused component files + ├── NAM_Common.yaml # Shared primitives (UUID, DateTime, ResourceAudit, securitySchemes) + ├── CAMARA_common.yaml # Shared CAMARA-style error responses + ├── AccessDetail.yaml # Discriminated access detail variants (Wi-Fi, Thread) + ├── Policy.yaml # Trust Domain policy schemas (maxDevices, bandwidth, egress) + ├── NetworkAccessDevices/ # Network Access Device resource schemas + ├── RebootRequests/ # Reboot Request lifecycle schemas + └── TrustDomains/ # Trust Domain & related capability schemas +``` + +## Architecture Rationale + +### Why Multiple Files? + +**Before:** Single monolithic OpenAPI file (`network-access-management.yaml`) +- ✅ Simple to understand initially +- ❌ Became very large (2000+ lines) +- ❌ Hard to maintain and review +- ❌ Schema duplication across different APIs +- ❌ Merge conflicts in collaborative development +- ❌ No reusability between different API specifications + +**After:** Modular component-based structure +- ✅ Each file has a single, clear responsibility +- ✅ Reusable schemas can be shared across APIs +- ✅ Easier to review and maintain individual components +- ✅ Parallel development by different team members +- ✅ Clear separation of concerns +- ✅ Smaller, focused files + +### Component Breakdown + +| File | Purpose | Reusability | +|------|---------|-------------| +| `Common.yaml` | Base types (UUID, DateTime, ErrorInfo) | High - used across all APIs | +| `Policy.yaml` | Trust Domain governance policies | Medium - Trust Domain specific | +| `AccessDetail.yaml` | Network access configurations | Medium - Network-related APIs | +| `TrustDomains.yaml` | Core Trust Domain schemas | Low - Trust Domain specific | + +## Bundling Process + +### Prerequisites + +Install Redocly CLI: +```bash +npm install -g @redocly/cli +``` + +### Creating Bundled Specifications + +The `redocly.yaml` configuration file defines how to bundle the modular components into complete API specifications. + +#### Bundle Network Access Management API +```bash +cd code/API_definitions +# Generate the complete Network Access Management API specification +redocly bundle Templates/network-access-management-template.yaml --output network-access-management-bundled.yaml + +# Validate the bundled specification +redocly lint network-access-management-bundled.yaml +``` + +#### Overwrite Official OpenAPI Specification + +Once you've created and validated a bundled specification, you can deploy it as the official API specification: + +**Manual Deployment:** +```bash +# After bundling and validation, overwrite the official specification +cp network-access-management-bundled.yaml network-access-management.yaml + +# Commit the updated official specification +git add network-access-management.yaml +git commit -m "Update official API specification from template" +``` + +**Automated Deployment:** +You can automate the bundling and deployment process using a script or CI/CD pipeline to ensure the official specification is always up-to-date with the latest templates. + +### Bundling Configuration + +The `redocly.yaml` file contains: +- **Linting rules** - Ensures consistency and quality +- **Bundling options** - Controls how references are resolved +- **Validation settings** - Catches errors early in development + +Key bundling features: +- Resolves all `$ref` references to external files +- Validates schema compatibility +- Generates self-contained OpenAPI specifications +- Preserves examples and documentation + +## File Purposes + +### Source Template Files + +- **`network-access-management-template.yaml`** - Main Network Access Management API template (source for bundling) + +### Generated API Files + +- **`network-access-management.yaml`** - Complete bundled Network Access Management API specification (generated from template) + +### Template Files + +- **`Templates/capabilities.yaml`** - Device capabilities API template +- **`Templates/network-access-management.yaml`** - Complete Network Access Management API template (alternative source) + +### Component Files + +- **`Domain/Common.yaml`** - Shared fundamental types (UUID, DateTime, Error schemas) +- **`Domain/Policy.yaml`** - Trust Domain policy schemas (maxDevices, bandwidth limits, egress rules) +- **`Domain/AccessDetail.yaml`** - Network access configuration schemas (Wi-Fi, Thread, security modes) +- **`Domain/TrustDomains/TrustDomains.yaml`** - Core Trust Domain schemas and examples + +## Best Practices + +### When to Create New Component Files +- **High reusability** - Schemas used by multiple APIs +- **Logical grouping** - Related schemas that form a cohesive unit +- **Size management** - When a file exceeds ~500 lines + +### Schema Design Guidelines +- Use `$ref` for external schema references +- Keep examples close to their schemas +- Use YAML anchors for internal reuse within files +- Document inheritance and discriminator patterns clearly + +### Example Cross-Reference Limitations + +**Important:** While schemas can be easily shared across files using `$ref`, examples have significant limitations in the distributed component model: + +#### The Problem +```yaml +# ❌ This does NOT work - cannot use $ref inside example values +TrustDomainExample: + summary: Trust Domain with Wi-Fi access + value: + name: "My Network" + accessDetails: + - $ref: "../AccessDetail.yaml#/components/examples/WiFiExample/value" # Invalid! +``` + +#### The Solutions + +**Option 1: Local Example Duplication (Recommended)** +```yaml +# ✅ Define examples locally where they're used +TrustDomainExample: + summary: Trust Domain with Wi-Fi access + value: + name: "My Network" + accessDetails: + - accessType: "Wi-Fi" + ssid: "my-network" + securityMode: + password: "my-password" + securityModeType: "WPA2-Personal" +``` + +**Option 2: YAML Anchors (Within Same File Only)** +```yaml +# ✅ Use anchors for reuse within the same file +_wifi_example: &wifi-access + accessType: "Wi-Fi" + ssid: "my-network" + securityMode: + password: "my-password" + securityModeType: "WPA2-Personal" + +components: + examples: + TrustDomainExample: + value: + accessDetails: + - *wifi-access # Reuse within same file +``` + +**Option 3: Component-Level Example References** +```yaml +# ✅ Reference complete examples at component level (not within values) +WiFiAccessExample: + $ref: "../AccessDetail.yaml#/components/examples/WiFiAccessDetailWPA2Personal" + +# But you still can't compose these inside other example values +``` diff --git a/code/API_definitions/capabilities.yaml b/code/API_definitions/Templates/capabilities-template.yaml similarity index 89% rename from code/API_definitions/capabilities.yaml rename to code/API_definitions/Templates/capabilities-template.yaml index c8f17ed..9ca7e25 100644 --- a/code/API_definitions/capabilities.yaml +++ b/code/API_definitions/Templates/capabilities-template.yaml @@ -33,14 +33,14 @@ paths: - network-access-management:device:read operationId: getDeviceCapabilities parameters: - - $ref: "./Domain/Common.yaml#/components/parameters/deviceIdParam" + - $ref: "../Domain/Capabilities.yaml#/components/parameters/deviceId" responses: "200": description: Capabilities supported by the device content: application/json: schema: - $ref: "./Domain/Capabilities.yaml#/components/schemas/DeviceCapabilities" + $ref: "../Domain/Capabilities.yaml#/components/schemas/DeviceCapabilities" "404": description: Device not found diff --git a/code/API_definitions/Templates/network-access-management-template.yaml b/code/API_definitions/Templates/network-access-management-template.yaml new file mode 100644 index 0000000..a107285 --- /dev/null +++ b/code/API_definitions/Templates/network-access-management-template.yaml @@ -0,0 +1,738 @@ +openapi: 3.0.3 + +info: + title: Home Devices - Network Access Management + license: + name: Apache 2.0 + url: https://www.apache.org/licenses/LICENSE-2.0.html + version: wip + x-camara-commonalities: 0.6 + description: | + Service enabling API for managing network operator supplied network access devices. This API's initial focus is on + managing **Trust Domains** and device reboot requests. + + # Introduction + A Trust Domain is a network access configuration where each configuration is for a logically separated Local + Area Network (LAN). API consumers 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. API consumers + 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 + - **Trust Domain**: a declarative, intent-level grouping that defines which devices are permitted to communicate with each other as if they were on the same LAN and what high-level access policies apply to that group. + - **Reboot Request**: A request to reboot a network operator supplied network access device. + - **Network Access Device**: A network operator supplied network access device that supports network segmentation technologies. Multiple devices + that support LAN connectivity across the same Trust Domain (e.g., mesh Wi-Fi, Thread personal area network, + etc.) SHOULD be presented as a single device for implementations of this API. + - **API Provider**: Provider that implements this API. + - **Network Operator**: Service provider that 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 a Trust Domain with a network client. + - **Network Client**: End-user equipment connecting to a Trust Domain (e.g., laptop, phone, IoT device, etc.). + - **API Consumer**: A first- or third-party software system using this API. + + # API Functionality + This API allows API Consumers to manage Trust Domains and reboot network access devices. + + ### Authorization and authentication + + The "CAMARA Security and Interoperability Profile" provides details of how an API consumer requests an access token. Please refer to Identity and Consent Management (https://github.com/camaraproject/IdentityAndConsentManagement/) for the released version of the profile. + + The specific authorization flows to be used will be agreed upon during the onboarding process, happening between the API consumer and the API provider, taking into account the declared purpose for accessing the API, whilst also being subject to the prevailing legal framework dictated by local legislation. + + In cases where personal 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 three-legged access tokens is mandatory. This ensures that the API remains in compliance with privacy regulations, upholding the principles of transparency and user-centric privacy-by-design. + + ### Scopes + Scopes are used to protect the service owner's information and privacy. The general format is + `--`. A resource may be further broken down into `-` or + `-` for granular permissions. Scopes also control output information as opposed to just + authorizing endpoints. Each endpoint definition will clearly state what scopes are needed for access and which are + needed to access additional information. Below are some general rules for scopes in this API. + + - Regulated information, such as physical locations or hardware addresses of network devices, have special scopes. + Network operators are expected to follow any local regulations when sharing this information with an API client. + - Scopes have inheritance when one scope would otherwise require the inherited scope. + - Read scopes for one resource impacts the output of another resource when the requested resource has a relationship + with the first (e.g., listing networks on a device requires both device and network read scopes). + + | Scope | Description | + |-------|-------------| + | **network-access-management:trust-domains** | Manage the caller's own Trust Domains (create, modify, delete, view). | + | **network-access-management:trust-domains:read-all** | Read all Trust Domains belonging to the subscriber, including those created by other clients (requires subscriber consent). | + | **network-access-management:reboot** | Create, list, and manage Reboot Requests for owned devices. | + | **network-access-management:services:read** | List services accessible to the authenticated identity | + + ## General Usage + This API is intended for creating, modifying, or deleting Trust Domains using the `/trust-domains` 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.). + + ## Comments for API Clients + + ### Reboot Requests + Reboot Requests provide a declarative mechanism for API clients to trigger an + immediate or scheduled reboot of one or more Network Access Devices associated + with a subscriber. The following clarifies expected behavior, device inference + rules, and recommended client patterns. + + #### Device Targeting + Clients MAY target devices in one of two ways: + + 1. **Explicit Targeting** + The client provides a `devices` array containing one or more device UUIDs. + This mode MUST be used when: + - multiple devices exist for the subscriber + - reboot is intended for a subset of devices + - the provider indicates that inference is unsupported + + 2. **Implicit (“Default Device”) Targeting** + Clients MAY omit the `devices` array to reboot a default device, if and only if: + - exactly one device is provisioned for the subscriber + - the provider supports inference + - the device is reboot-capable + + If inference fails, the request MUST be rejected (e.g., 400 INVALID_ARGUMENT or + 422 MISSING_IDENTIFIER). + + #### Behavior Guarantees + + - If `devices` is omitted and inference succeeds, the response MUST contain the + provider-resolved device list. + - Validation is atomic: if any device ID is invalid, unauthorized, or not + reboot-capable, the request MUST fail without side effects. + - Partial success is not allowed. + - Providers MAY reject duplicate reboot requests targeting the same devices and time. + + #### Interaction with Related Endpoints + + - `GET /network-access-devices` + Used to enumerate devices and their configuration. + + - `POST /reboot-requests` + Create a reboot request (immediate or scheduled). + + - `GET /reboot-requests/{id}` + Retrieve the status of a previously-created request. Implementations MAY extend + the status model over time. + + #### Recommended Client Flow + + 1. (Optional) Query device capabilities using `/network-access-devices`. + 2. If multiple devices exist or inference is unsupported, build an explicit + device list. + 3. Create the reboot request with immediate or scheduled execution (`atTime`). + 4. (Optional) Poll the individual reboot request status for asynchronous flows. + + ## Comments for Network Operators + The following comments are for Network Operators implementing this API. + + ### Auto-Deleting Trust Domains + When a Trust Domain is not configured on any device the network configuration and its identifier SHOULD be + auto-deleted. API clients MUST not be expected to delete Trust Domains 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 Trust Domain. 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 Trust Domains 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. + + # Additional CAMARA error responses + + The list of error codes in this API specification is not exhaustive. Therefore the API specification may not document some non-mandatory error statuses as indicated in `CAMARA API Design Guide`. + + Please refer to the `CAMARA_common.yaml` of the Commonalities Release associated to this API version for a complete list of error responses. The applicable Commonalities Release can be identified in the `API Readiness Checklist` document associated to this API version. + + As a specific rule, error `501 - NOT_IMPLEMENTED` can be only a possible error response if it is explicitly documented in the API. + +externalDocs: + description: Product documentation at CAMARA + url: https://github.com/camaraproject/NetworkAccessManagement + +servers: + - url: "{apiRoot}/network-access-management/vwip" + 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: Services + description: Operations to list network services accessible to the authenticated identity + - name: Trust Domains + description: Operations to Create and Manage Trust Domains + - name: Reboot Requests + description: | + Operations to Create and Manage Reboot Requests for Network Access Devices + +paths: + + /services: + get: + tags: + - Services + summary: Get all services accessible to the authenticated identity + security: + - openId: + - network-access-management:services:read + operationId: getServices + description: | + Returns all services accessible to the calling identity. Services represent + a logical commercial relationship between a subscriber and a network operator, + typically corresponding to a unique service account or subscription. + + This endpoint supports workflows where an API Consumer (e.g., AirBnB, Amazon) + has received subscriber authorization and must enumerate services to link with + Network Client Devices or Trust Domains. + + responses: + "200": + description: Contains all services associated with the identity + content: + application/json: + schema: + $ref: "../Domain/Services/Services.yaml#/components/schemas/ServiceList" + "401": + $ref: "../Domain/CAMARA_common.yaml#/components/responses/Generic401" + "403": + $ref: "../Domain/CAMARA_common.yaml#/components/responses/Generic403" + "500": + $ref: "../Domain/CAMARA_common.yaml#/components/responses/Generic500" + + + /services/{serviceId}: + get: + tags: + - Services + summary: Get a service by ID + security: + - openId: + - network-access-management:services:read + operationId: getService + description: | + Returns a specific service corresponding to the given `serviceId`. + + This can be used to inspect service metadata prior to using it in other + API operations such as Trust Domain creation. + + **Required Scopes:** + - `network-access-management:services:read` + + parameters: + - name: serviceId + in: path + required: true + schema: + $ref: "../Domain/Services/Services.yaml#/components/schemas/ServiceId" + description: | + The ID of the service to retrieve. + + Must be a valid UUID as defined by RFC 4122 (versions 1-5) using only lowercase hexadecimal characters. + responses: + "200": + description: Information about the service + content: + application/json: + schema: + $ref: "../Domain/Services/Services.yaml#/components/schemas/Service" + "401": + $ref: "../Domain/CAMARA_common.yaml#/components/responses/Generic401" + "403": + $ref: "../Domain/CAMARA_common.yaml#/components/responses/Generic403" + "404": + $ref: "../Domain/CAMARA_common.yaml#/components/responses/Generic404" + "500": + $ref: "../Domain/CAMARA_common.yaml#/components/responses/Generic500" + + /trust-domains/capabilities: + get: + tags: + - Trust Domains + summary: Get Trust Domain capabilities + security: + - openId: + - network-access-management:trust-domains + operationId: getTrustDomainCapabilities + description: | + Retrieves the set of Trust Domain configuration capabilities supported by the API provider. + Capabilities describe supported access types, policy constraints, and configuration limits. + + This endpoint enables API clients to discover: + - Which access types are supported (Wi-Fi variants, Thread modes, etc.) + - What policy types are available + - Operational limits and constraints + - Advanced features and configuration options + + Use this endpoint before creating Trust Domains to ensure your configuration + is supported by the target API provider/network operator. + + responses: + "200": + description: Trust Domain capabilities supported by this API provider + content: + application/json: + schema: + $ref: "../Domain/TrustDomains/TrustDomainCapabilities.yaml#/components/schemas/TrustDomainCapabilities" + "403": + $ref: "../Domain/CAMARA_common.yaml#/components/responses/Generic403" + "500": + $ref: "../Domain/CAMARA_common.yaml#/components/responses/Generic500" + "503": + $ref: "../Domain/CAMARA_common.yaml#/components/responses/Generic503" + + /trust-domains: + post: + tags: + - Trust Domains + summary: Create a new Trust Domain + security: + - openId: + - network-access-management:trust-domains + description: | + Creates and returns the new Trust Domain. + + operationId: createTrustDomain + requestBody: + description: Details of the Trust Domain to be created + required: true + content: + application/json: + schema: + $ref: '../Domain/TrustDomains/TrustDomains.yaml#/components/schemas/TrustDomainCreate' + examples: + TrustDomainCreateWpa2Personal: + $ref: '../Domain/TrustDomains/TrustDomains.yaml#/components/examples/TrustDomainCreateWpa2Personal' + TrustDomainCreateInferredSsid: + $ref: '../Domain/TrustDomains/TrustDomains.yaml#/components/examples/TrustDomainCreateInferredSsid' + TrustDomainCreateThreadStructured: + $ref: '../Domain/TrustDomains/TrustDomains.yaml#/components/examples/TrustDomainCreateThreadStructured' + TrustDomainCreateEphemeral: + $ref: '../Domain/TrustDomains/TrustDomains.yaml#/components/examples/TrustDomainCreateEphemeral' + TrustDomainCreateQoSPolicies: + $ref: '../Domain/TrustDomains/TrustDomains.yaml#/components/examples/TrustDomainCreateQoSPolicies' + responses: + '201': + description: Trust Domain created successfully + content: + application/json: + schema: + $ref: '../Domain/TrustDomains/TrustDomains.yaml#/components/schemas/TrustDomain' + examples: + TrustDomainResponseBasic: + $ref: '../Domain/TrustDomains/TrustDomains.yaml#/components/examples/TrustDomainResponseBasic' + TrustDomainResponseWiFiThread: + $ref: '../Domain/TrustDomains/TrustDomains.yaml#/components/examples/TrustDomainResponseWiFiThread' + '400': + $ref: '../Domain/CAMARA_common.yaml#/components/responses/Generic400' + '403': + $ref: '../Domain/CAMARA_common.yaml#/components/responses/Generic403' + '409': + $ref: '../Domain/CAMARA_common.yaml#/components/responses/Generic409' + '500': + $ref: '../Domain/CAMARA_common.yaml#/components/responses/Generic500' + + get: + tags: + - Trust Domains + summary: Retrieves all Trust Domains visible to the calling API client + security: + - openId: + - network-access-management:trust-domains + - openId: + - network-access-management:trust-domains:read-all + operationId: getTrustDomains + description: | + Retrieves all Trust Domains visible to the calling API client. + + If the caller has `network-access-management:trust-domains`, the response is limited to + Trust Domains created by the caller. If the caller has `network-access-management:trust-domains:read-all`, + the response includes all Trust Domains associated with the subscriber. + responses: + + "200": + description: Contains information about all trust domains + content: + application/json: + schema: + type: array + items: + $ref: "../Domain/TrustDomains/TrustDomains.yaml#/components/schemas/TrustDomain" + "403": + $ref: "../Domain/CAMARA_common.yaml#/components/responses/Generic403" + "500": + $ref: "../Domain/CAMARA_common.yaml#/components/responses/Generic500" + "503": + $ref: "../Domain/CAMARA_common.yaml#/components/responses/Generic503" + + /trust-domains/{trustDomainId}: + parameters: + - $ref: '../Domain/TrustDomains/TrustDomains.yaml#/components/parameters/trustDomainId' + + get: + tags: + - Trust Domains + summary: Get a specific Trust Domain + security: + - openId: + - network-access-management:trust-domains + - openId: + - network-access-management:trust-domains:read-all + operationId: getTrustDomain + description: | + Retrieves the Trust Domain identified by the given ID. Visibility of this Trust Domain depends on the caller's scope and ownership: + - `trust-domains` restricts access to caller-owned Trust Domains. + - `trust-domains:read-all` allows retrieval of any Trust Domain associated with the subscriber. + + responses: + + "200": + description: Contains information about the specified trust domain + content: + application/json: + schema: + $ref: "../Domain/TrustDomains/TrustDomains.yaml#/components/schemas/TrustDomain" + examples: + TrustDomainResponseBasic: + $ref: '../Domain/TrustDomains/TrustDomains.yaml#/components/examples/TrustDomainResponseBasic' + "403": + $ref: "../Domain/CAMARA_common.yaml#/components/responses/Generic403" + "404": + $ref: "../Domain/CAMARA_common.yaml#/components/responses/Generic404" + "500": + $ref: "../Domain/CAMARA_common.yaml#/components/responses/Generic500" + "503": + $ref: "../Domain/CAMARA_common.yaml#/components/responses/Generic503" + + patch: + tags: + - Trust Domains + summary: Update a specific Trust Domain + security: + - openId: + - network-access-management:trust-domains + operationId: updateTrustDomain + description: | + Updates the Trust Domain identified by the given ID. Any changes are automatically applied to all network access devices where the Trust Domain is configured. + + requestBody: + content: + application/json: + schema: + $ref: "../Domain/TrustDomains/TrustDomains.yaml#/components/schemas/TrustDomainUpdate" + required: true + responses: + "200": + description: Contains information about the updated trust domain + content: + application/json: + schema: + $ref: "../Domain/TrustDomains/TrustDomains.yaml#/components/schemas/TrustDomain" + + "400": + $ref: "../Domain/CAMARA_common.yaml#/components/responses/Generic400" + "403": + $ref: "../Domain/CAMARA_common.yaml#/components/responses/Generic403" + "404": + $ref: "../Domain/CAMARA_common.yaml#/components/responses/Generic404" + "500": + $ref: "../Domain/CAMARA_common.yaml#/components/responses/Generic500" + "503": + $ref: "../Domain/CAMARA_common.yaml#/components/responses/Generic503" + + delete: + tags: + - Trust Domains + summary: Delete a specific Trust Domain + security: + - openId: + - network-access-management:trust-domains + operationId: deleteTrustDomain + description: | + Deletes the Trust Domain identified by the given ID and removes its configuration from all network access devices where it is applied. + + responses: + "204": + description: Trust Domain deleted successfully + "403": + $ref: "../Domain/CAMARA_common.yaml#/components/responses/Generic403" + "404": + $ref: "../Domain/CAMARA_common.yaml#/components/responses/Generic404" + "500": + $ref: "../Domain/CAMARA_common.yaml#/components/responses/Generic500" + "503": + $ref: "../Domain/CAMARA_common.yaml#/components/responses/Generic503" + + /network-access-devices: + get: + tags: + - Reboot Requests + summary: Get all Network Access Devices associated with the service owner + security: + - openId: + - network-access-management:reboot + operationId: getNetworkAccessDevices + description: | + Retrieves all Network Access Devices associated with the subscriber that the caller is authorized to manage using the `network-access-management:reboot` scope. + responses: + "200": + description: Contains the list of network access devices + content: + application/json: + schema: + $ref: "../Domain/NetworkAccessDevices/NetworkAccessDevices.yaml#/components/schemas/NetworkAccessDeviceList" + "400": + $ref: "../Domain/CAMARA_common.yaml#/components/responses/Generic400" + "403": + $ref: "../Domain/CAMARA_common.yaml#/components/responses/Generic403" + "404": + $ref: "../Domain/CAMARA_common.yaml#/components/responses/Generic404" + "500": + $ref: "../Domain/CAMARA_common.yaml#/components/responses/Generic500" + "503": + $ref: "../Domain/CAMARA_common.yaml#/components/responses/Generic503" + + /network-access-devices/{networkAccessDeviceId}: + get: + tags: + - Reboot Requests + summary: Get a specific Network Access Device + security: + - openId: + - network-access-management:reboot + operationId: getNetworkAccessDevice + description: | + Retrieves the Network Access Device that matches the given ID. + parameters: + - $ref: '../Domain/NetworkAccessDevices/NetworkAccessDevices.yaml#/components/parameters/networkAccessDeviceId' + responses: + "200": + description: Contains information about the specified network access device + content: + application/json: + schema: + $ref: "../Domain/NetworkAccessDevices/NetworkAccessDevices.yaml#/components/schemas/NetworkAccessDevice" + "400": + $ref: "../Domain/CAMARA_common.yaml#/components/responses/Generic400" + "403": + $ref: "../Domain/CAMARA_common.yaml#/components/responses/Generic403" + "404": + $ref: "../Domain/CAMARA_common.yaml#/components/responses/Generic404" + "500": + $ref: "../Domain/CAMARA_common.yaml#/components/responses/Generic500" + "503": + $ref: "../Domain/CAMARA_common.yaml#/components/responses/Generic503" + + /reboot-requests: + post: + tags: + - Reboot Requests + summary: Create a new Reboot Request + security: + - openId: + - network-access-management:reboot + description: | + Creates a new Reboot Request targeting one or more Network Access Devices. + operationId: createRebootRequest + requestBody: + description: | + Creates a reboot request for one or more network access devices. Supports two targeting modes: + + Targeting modes: + - Inferred (implicit/default device): Omit the 'devices' array to request a reboot of the single + default device associated with the subscriber context. This is only valid when exactly one + device is eligible. If no default device exists or multiple devices are provisioned, the + request MUST be rejected (e.g. 400 INVALID_ARGUMENT or 422 MISSING_IDENTIFIER). + - Explicit (targeted devices): Provide a 'devices' array of one or more device UUIDs to request + reboots on those specific devices. Validation MUST fail if any supplied device ID is unknown, + not reboot-capable, or the caller lacks authorization. + + Scheduling: + - Immediate reboot: Omit 'atTime'. + - Scheduled reboot: Include 'atTime' (RFC 3339 with timezone). Time MUST be in the future; past + values SHOULD produce a 400 OUT_OF_RANGE error. + + Idempotency / duplication: + - Multiple identical pending reboot requests (same device set and same atTime) MAY be rejected + with 409 CONFLICT or collapsed by implementation. + + Error conditions (examples): + - 400 INVALID_ARGUMENT: Unsupported time format, too many device IDs, malformed UUID. + - 404 IDENTIFIER_NOT_FOUND: One or more device IDs not found. + - 403 PERMISSION_DENIED: Caller lacks scope or device ownership. + - 409 CONFLICT: Reboot already scheduled for the same devices and time. + - 422 MISSING_IDENTIFIER (implementation-specific): 'devices' omitted but no default device. + + Behavioral guarantees: + - If 'devices' omitted and inference succeeds, the response MUST reflect the resolved device list. + - If any device fails validation, no reboot request is created (atomic failure). + - Partial success is NOT permitted. + required: true + content: + application/json: + schema: + $ref: '../Domain/RebootRequests/RebootRequests.yaml#/components/schemas/RebootRequestCreate' + examples: + RebootRequestCreateImmediate: + $ref: '../Domain/RebootRequests/RebootRequests.yaml#/components/examples/RebootRequestCreateImmediateDefaultDevice' + RebootRequestCreateScheduled: + $ref: '../Domain/RebootRequests/RebootRequests.yaml#/components/examples/RebootRequestCreateScheduledMultipleDevices' + responses: + '201': + description: Reboot Request created successfully + content: + application/json: + schema: + $ref: '../Domain/RebootRequests/RebootRequests.yaml#/components/schemas/RebootRequest' + '400': + $ref: '../Domain/CAMARA_common.yaml#/components/responses/Generic400' + '403': + $ref: '../Domain/CAMARA_common.yaml#/components/responses/Generic403' + '404': + $ref: '../Domain/CAMARA_common.yaml#/components/responses/Generic404' + '409': + $ref: '../Domain/CAMARA_common.yaml#/components/responses/Generic409' + '422': + $ref: '../Domain/CAMARA_common.yaml#/components/responses/Generic422' + '500': + $ref: '../Domain/CAMARA_common.yaml#/components/responses/Generic500' + + get: + tags: + - Reboot Requests + summary: Get all Reboot Requests created by the calling API client + security: + - openId: + - network-access-management:reboot + operationId: getRebootRequests + description: | + This endpoint returns a list of Reboot Requests associated with the service owner created by the calling API client. + responses: + '200': + description: Contains information about all reboot requests + content: + application/json: + schema: + type: array + items: + $ref: '../Domain/RebootRequests/RebootRequests.yaml#/components/schemas/RebootRequest' + '400': + $ref: '../Domain/CAMARA_common.yaml#/components/responses/Generic400' + '403': + $ref: '../Domain/CAMARA_common.yaml#/components/responses/Generic403' + '500': + $ref: '../Domain/CAMARA_common.yaml#/components/responses/Generic500' + + /reboot-requests/{rebootRequestId}: + parameters: + - $ref: '../Domain/RebootRequests/RebootRequests.yaml#/components/parameters/rebootRequestId' + + get: + tags: + - Reboot Requests + summary: Get a specific Reboot Request + security: + - openId: + - network-access-management:reboot + operationId: getRebootRequest + description: | + Retrieves the Reboot Request that matches the given ID. + responses: + '200': + description: Contains information about the specified Reboot Request + content: + application/json: + schema: + $ref: '../Domain/RebootRequests/RebootRequests.yaml#/components/schemas/RebootRequest' + '400': + $ref: '../Domain/CAMARA_common.yaml#/components/responses/Generic400' + '403': + $ref: '../Domain/CAMARA_common.yaml#/components/responses/Generic403' + '404': + $ref: '../Domain/CAMARA_common.yaml#/components/responses/Generic404' + '500': + $ref: '../Domain/CAMARA_common.yaml#/components/responses/Generic500' + + patch: + tags: + - Reboot Requests + summary: Update an existing Reboot Request + security: + - openId: + - network-access-management:reboot + description: | + Updates an existing Reboot Request to modify its scheduled time or cancel it. + operationId: updateRebootRequest + requestBody: + content: + application/json: + schema: + $ref: '../Domain/RebootRequests/RebootRequests.yaml#/components/schemas/RebootRequestUpdate' + required: true + responses: + '200': + description: Reboot Request updated successfully + content: + application/json: + schema: + $ref: '../Domain/RebootRequests/RebootRequests.yaml#/components/schemas/RebootRequest' + '400': + $ref: '../Domain/CAMARA_common.yaml#/components/responses/Generic400' + '403': + $ref: '../Domain/CAMARA_common.yaml#/components/responses/Generic403' + '404': + $ref: '../Domain/CAMARA_common.yaml#/components/responses/Generic404' + '409': + $ref: '../Domain/CAMARA_common.yaml#/components/responses/Generic409' + '422': + $ref: '../Domain/CAMARA_common.yaml#/components/responses/Generic422' + '500': + $ref: '../Domain/CAMARA_common.yaml#/components/responses/Generic500' + + delete: + tags: + - Reboot Requests + summary: Delete an existing Reboot Request + security: + - openId: + - network-access-management:reboot + description: | + Deletes an existing Reboot Request, cancelling the scheduled reboot if it has not yet occurred. + operationId: deleteRebootRequest + responses: + '204': + description: Reboot Request deleted successfully + '400': + $ref: '../Domain/CAMARA_common.yaml#/components/responses/Generic400' + '403': + $ref: '../Domain/CAMARA_common.yaml#/components/responses/Generic403' + '404': + $ref: '../Domain/CAMARA_common.yaml#/components/responses/Generic404' + '500': + $ref: '../Domain/CAMARA_common.yaml#/components/responses/Generic500' + +components: + securitySchemes: + openId: + $ref: '../Domain/NAM_Common.yaml#/components/securitySchemes/openId' diff --git a/code/API_definitions/network-access-management.yaml b/code/API_definitions/network-access-management.yaml index 45d1c40..dd837e7 100644 --- a/code/API_definitions/network-access-management.yaml +++ b/code/API_definitions/network-access-management.yaml @@ -1,13 +1,17 @@ openapi: 3.0.3 - info: title: Home Devices - Network Access Management + license: + name: Apache 2.0 + url: https://www.apache.org/licenses/LICENSE-2.0.html + version: wip + x-camara-commonalities: 0.6 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 API's initial focus is on + managing **Trust Domains** and device reboot requests. # Introduction - An isolated network is a network access configuration where each configuration is for a logically separated Local + A Trust Domain is a network access configuration where each configuration is for a logically separated Local Area Network (LAN). API consumers can create, modify, or remove these networks which could be useful in scenarios such as: @@ -24,15 +28,10 @@ info: - 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. + - **Trust Domain**: a declarative, intent-level grouping that defines which devices are permitted to communicate with each other as if they were on the same LAN and what high-level access policies apply to that group. - **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, + - **Network Access Device**: A network operator supplied network access device that supports network segmentation technologies. Multiple devices + that support LAN connectivity across the same Trust Domain (e.g., mesh Wi-Fi, Thread personal area network, etc.) SHOULD be presented as a single device for implementations of this API. - **API Provider**: Provider that implements this API. - **Network Operator**: Service provider that has operational control of supporting devices. @@ -44,16 +43,16 @@ info: 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. + - **End-User**: The user connecting to a Trust Domain with a network client. + - **Network Client**: End-user equipment connecting to a Trust Domain (e.g., laptop, phone, IoT device, etc.). + - **API Consumer**: 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. + This API allows API Consumers to manage Trust Domains and reboot network access devices. ### Authorization and authentication - The "Camara Security and Interoperability Profile" provides details of how an API consumer requests an access token. Please refer to Identity and Consent Management (https://github.com/camaraproject/IdentityAndConsentManagement/) for the released version of the profile. + The "CAMARA Security and Interoperability Profile" provides details of how an API consumer requests an access token. Please refer to Identity and Consent Management (https://github.com/camaraproject/IdentityAndConsentManagement/) for the released version of the profile. The specific authorization flows to be used will be agreed upon during the onboarding process, happening between the API consumer and the API provider, taking into account the declared purpose for accessing the API, whilst also being subject to the prevailing legal framework dictated by local legislation. @@ -71,35 +70,16 @@ info: - Scopes have inheritance when one scope would otherwise require the inherited scope. - Read scopes for one resource impacts the output of another resource when the requested resource has a relationship with the first (e.g., listing networks on a device requires both device and network read scopes). - - Isolated networks are broken down into 3 roles allowing service owners to grant granular permissions to API - clients: only-own, primary, and auxiliary. The primary role allows API clients to manage the main network access - configuration. The auxiliary role allows API clients to manage all auxiliary (i.e., secondary) networks. The - only-own role allows API clients to manage networks it has created. Only-own networks SHOULD be an auxiliary, or - secondary, network. Note that there is an edge case when a service owner revokes the primary role authorization. An - API client SHOULD be able to continue managing primary isolated networks created by the client. Complete - administrative control requires both the primary and auxiliary roles. - | Scope | Description | Inherits - |-------|-------------|--------- - | **network-access-management:service-sites:read** | List a service owner's service sites - | **network-access-management:service-sites.location:read** | Read a service site's physical location | network-access-management:service-sites:read - | **network-access-management:devices:read** | List a service owner's devices - | **network-access-management:devices.hardware-address:read** | Read a service owner's device's hardware address | network-access-management:devices:read - | **network-access-management:devices:write** | Modify which networks are configured on a service owner's devices | network-access-management:devices:read - | **network-access-management:isolated-networks:wifi:read** | List a service owner's Wi-Fi isolated networks created by the calling API client - | **network-access-management:isolated-networks:wifi:write** | Create or modify a service owner's Wi-Fi isolated networks created by the calling API client | network-access-management:isolated-networks:wifi:read - | **network-access-management:isolated-networks:wifi.primary:read** | Access information about a service owner's Wi-Fi primary isolated network - | **network-access-management:isolated-networks:wifi.primary:write** | Modify a service owner's primary Wi-Fi isolated network | network-access-management:isolated-networks:wifi.primary:read - | **network-access-management:isolated-networks:wifi.auxiliary:read** | List a service owner's auxiliary Wi-Fi isolated networks | network-access-management:isolated-networks:wifi:read - | **network-access-management:isolated-networks:wifi.auxiliary:write** | Create or modify a service owner's Wi-Fi auxiliary isolated networks | network-access-management:isolated-networks:wifi.auxiliary:read
network-access-management:isolated-networks:wifi:write - | **network-access-management:isolated-networks:thread:read** | Read the Thread credentials if they are the API provider's default or the requesting client formed the network - | **network-access-management:isolated-networks:thread:form** | Form a new Thread network, replacing the API provider's default Thread network if applicable, and modify or delete the existing network if created by the requesting client | network-access-management:isolated-networks:thread:read - | **network-access-management:isolated-networks:thread.admin** | Read or write to any of the service owner's Thread networks | network-access-management:isolated-networks:thread:form - | **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 + | Scope | Description | + |-------|-------------| + | **network-access-management:trust-domains** | Manage the caller's own Trust Domains (create, modify, delete, view). | + | **network-access-management:trust-domains:read-all** | Read all Trust Domains belonging to the subscriber, including those created by other clients (requires subscriber consent). | + | **network-access-management:reboot** | Create, list, and manage Reboot Requests for owned devices. | + | **network-access-management:services:read** | List services accessible to the authenticated identity | ## General Usage - This API is intended for creating, modifying, or deleting isolated networks using the `/isolated-networks` endpoints + This API is intended for creating, modifying, or deleting Trust Domains using the `/trust-domains` 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 @@ -107,25 +87,74 @@ info: may be requested for the same purpose of reconciling information from another source (e.g., database, persons with physical device access, etc.). - ## Default Device Mode - When an identity for access token has a "default device", such as a typical residential customer with one service - site and one network access device, service site and device scopes MAY be omitted. Any fields referencing a - network access device using the `/isolated-networks` or `/isolated-networks/*` APIs MUST be left blank by API - clients. Network operators SHOULD substitute the missing field with the default device. API definitions include - additional details for error responses so API clients can detect if this mode is available. + ## Comments for API Clients + + ### Reboot Requests + Reboot Requests provide a declarative mechanism for API clients to trigger an + immediate or scheduled reboot of one or more Network Access Devices associated + with a subscriber. The following clarifies expected behavior, device inference + rules, and recommended client patterns. + + #### Device Targeting + Clients MAY target devices in one of two ways: + + 1. **Explicit Targeting** + The client provides a `devices` array containing one or more device UUIDs. + This mode MUST be used when: + - multiple devices exist for the subscriber + - reboot is intended for a subset of devices + - the provider indicates that inference is unsupported + + 2. **Implicit (“Default Device”) Targeting** + Clients MAY omit the `devices` array to reboot a default device, if and only if: + - exactly one device is provisioned for the subscriber + - the provider supports inference + - the device is reboot-capable + + If inference fails, the request MUST be rejected (e.g., 400 INVALID_ARGUMENT or + 422 MISSING_IDENTIFIER). + + #### Behavior Guarantees + + - If `devices` is omitted and inference succeeds, the response MUST contain the + provider-resolved device list. + - Validation is atomic: if any device ID is invalid, unauthorized, or not + reboot-capable, the request MUST fail without side effects. + - Partial success is not allowed. + - Providers MAY reject duplicate reboot requests targeting the same devices and time. + + #### Interaction with Related Endpoints + + - `GET /network-access-devices` + Used to enumerate devices and their configuration. + + - `POST /reboot-requests` + Create a reboot request (immediate or scheduled). + + - `GET /reboot-requests/{id}` + Retrieve the status of a previously-created request. Implementations MAY extend + the status model over time. + + #### Recommended Client Flow + + 1. (Optional) Query device capabilities using `/network-access-devices`. + 2. If multiple devices exist or inference is unsupported, build an explicit + device list. + 3. Create the reboot request with immediate or scheduled execution (`atTime`). + 4. (Optional) Poll the individual reboot request status for asynchronous flows. ## 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. + ### Auto-Deleting Trust Domains + When a Trust Domain is not configured on any device the network configuration and its identifier SHOULD be + auto-deleted. API clients MUST not be expected to delete Trust Domains 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 + LAN connectivity across multiple devices with the same Trust Domain. 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 + may be used. If an end-user replaces the equipment, all existing Trust Domains 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. @@ -136,1356 +165,614 @@ info: Please refer to the `CAMARA_common.yaml` of the Commonalities Release associated to this API version for a complete list of error responses. The applicable Commonalities Release can be identified in the `API Readiness Checklist` document associated to this API version. As a specific rule, error `501 - NOT_IMPLEMENTED` can be only a possible error response if it is explicitly documented in the API. - - license: - name: Apache 2.0 - url: https://www.apache.org/licenses/LICENSE-2.0.html - version: wip - x-camara-commonalities: 0.6.0 - contact: - email: sp-nam@lists.camaraproject.org - servers: - - url: "{apiRoot}/network-access-management/vwip" + - url: '{apiRoot}/network-access-management/vwip' variables: apiRoot: default: http://localhost:9091 description: API root, defined by the service provider, e.g. `api.example.com` or `api.example.com/somepath` - tags: - - name: Retrieve Service Site - description: Operations to retrieve information about service sites - - name: Retrieve Device - description: Operations to retrieve information about devices - - name: Apply Device Network Configuration - description: Operations to apply isolated network configurations to devices - - name: Retrieve Isolated Network - description: Operations to retrieve information about isolated networks - - name: Configure and Apply Isolated Network - description: Operations to modify isolated networks and apply to devices - - name: Retrieve Reboot Request - description: Operations to retrieve information about reboot requests - - name: Configure Reboot Requests - description: Operations to modify reboot requests - + - name: Services + description: Operations to list network services accessible to the authenticated identity + - name: Trust Domains + description: Operations to Create and Manage Trust Domains + - name: Reboot Requests + description: | + Operations to Create and Manage Reboot Requests for Network Access Devices +externalDocs: + description: Product documentation at CAMARA + url: https://github.com/camaraproject/NetworkAccessManagement paths: - /service-sites: + /services: get: tags: - - Retrieve Service Site - summary: Get all service sites + - Services + summary: Get all services accessible to the authenticated identity security: - openId: - - network-access-management:service-sites:read - operationId: getServiceSites + - network-access-management:services:read + operationId: getServices description: | - Returns all service sites. Scopes impact the output of this endpoint. See the examples for various - permutations. - - **Required Scopes:** - - **one of** - - `network-access-management:service-sites:read` - - `network-access-management:service-sites.location:read` + Returns all services accessible to the calling identity. Services represent + a logical commercial relationship between a subscriber and a network operator, + typically corresponding to a unique service account or subscription. - **Optional Scopes:** - - `network-access-management:devices:read` - - `network-access-management:devices:write` - - `network-access-management:devices.hardware-address:read` + This endpoint supports workflows where an API Consumer (e.g., AirBnB, Amazon) + has received subscriber authorization and must enumerate services to link with + Network Client Devices or Trust Domains. responses: - "200": - description: Contains information about all service sites + '200': + description: Contains all services associated with the identity 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}: + $ref: '#/components/schemas/ServiceList' + '401': + $ref: '#/components/responses/Generic401' + '403': + $ref: '#/components/responses/Generic403' + '500': + $ref: '#/components/responses/Generic500' + /services/{serviceId}: get: tags: - - Retrieve Service Site - summary: Get a service site by ID + - Services + summary: Get a service by ID security: - openId: - - network-access-management:service-sites:read - operationId: getServiceSite + - network-access-management:services:read + operationId: getService 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 specific service corresponding to the given `serviceId`. - **Required Scopes:** - - **one of** - - `network-access-management:service-sites:read` - - `network-access-management:service-sites.location:read` + This can be used to inspect service metadata prior to using it in other + API operations such as Trust Domain creation. - **Optional Scopes:** - - `network-access-management:devices:read` - - `network-access-management:devices:write` - - `network-access-management:devices.hardware-address:read` + **Required Scopes:** + - `network-access-management:services:read` parameters: - - $ref: "#/components/parameters/siteId" + - name: serviceId + in: path + required: true + schema: + $ref: '#/components/schemas/ServiceId' + description: | + The ID of the service to retrieve. + + Must be a valid UUID as defined by RFC 4122 (versions 1-5) using only lowercase hexadecimal characters. responses: - "200": - description: Contains information about the service site + '200': + description: Information about the service 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/Generic404" - "500": - $ref: "#/components/responses/Generic500" - "501": - $ref: "#/components/responses/Generic501" - "503": - $ref: "#/components/responses/Generic503" - - /service-sites/{siteId}/devices: + $ref: '#/components/schemas/Service' + '401': + $ref: '#/components/responses/Generic401' + '403': + $ref: '#/components/responses/Generic403' + '404': + $ref: '#/components/responses/Generic404' + '500': + $ref: '#/components/responses/Generic500' + /trust-domains/capabilities: get: tags: - - Retrieve Device - summary: Get all devices at a service site + - Trust Domains + summary: Get Trust Domain capabilities security: - openId: - - network-access-management:service-sites:read - - network-access-management:devices:read - operationId: getDevicesByServiceSite + - network-access-management:trust-domains + operationId: getTrustDomainCapabilities 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. + Retrieves the set of Trust Domain configuration capabilities supported by the API provider. + Capabilities describe supported access types, policy constraints, and configuration limits. - **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` + This endpoint enables API clients to discover: + - Which access types are supported (Wi-Fi variants, Thread modes, etc.) + - What policy types are available + - Operational limits and constraints + - Advanced features and configuration options - **Optional Scopes:** - - `network-access-management:isolated-networks:wifi:read` - - `network-access-management:isolated-networks:wifi:write` - - `network-access-management:isolated-networks:wifi.primary:read` - - `network-access-management:isolated-networks:wifi.primary:write` - - `network-access-management:isolated-networks:wifi.auxiliary:read` - - `network-access-management:isolated-networks:wifi.auxiliary:write` - parameters: - - $ref: "#/components/parameters/siteId" + Use this endpoint before creating Trust Domains to ensure your configuration + is supported by the target API provider/network operator. responses: - "200": - description: Contains information about devices at the service site + '200': + description: Trust Domain capabilities supported by this API provider 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/Generic404" - "500": - $ref: "#/components/responses/Generic500" - "501": - $ref: "#/components/responses/Generic501" - "503": - $ref: "#/components/responses/Generic503" - - /service-sites/{siteId}/isolated-networks: - get: + $ref: '#/components/schemas/TrustDomainCapabilities' + '403': + $ref: '#/components/responses/Generic403' + '500': + $ref: '#/components/responses/Generic500' + '503': + $ref: '#/components/responses/Generic503' + /trust-domains: + post: tags: - - Retrieve Service Site - summary: Get all networks at a service site + - Trust Domains + summary: Create a new Trust Domain security: - openId: - - network-access-management:service-sites:read - - network-access-management:devices:read - - network-access-management:isolated-networks:wifi:read - operationId: getNetworksByServiceSite + - network-access-management:trust-domains description: | - Returns all networks at a service site that matches the given ID. - - **Required Scopes:** - - **all of** - - **one of** - - `network-access-management:service-sites:read` - - `network-access-management:service-sites.location:read` - - **one of** - - `network-access-management:devices:read` - - `network-access-management:devices:write` - - `network-access-management:devices.hardware-address:read` - - **one of** - - `network-access-management:isolated-networks:wifi:read` - - `network-access-management:isolated-networks:wifi:write` - - `network-access-management:isolated-networks:wifi.primary:read` - - `network-access-management:isolated-networks:wifi.primary:write` - - `network-access-management:isolated-networks:wifi.auxiliary:read` - - `network-access-management:isolated-networks:wifi.auxiliary:write` - parameters: - - $ref: "#/components/parameters/siteId" + Creates and returns the new Trust Domain. + operationId: createTrustDomain + requestBody: + description: Details of the Trust Domain to be created + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/TrustDomainCreate' + examples: + TrustDomainCreateWpa2Personal: + $ref: '#/components/examples/TrustDomainCreateWpa2Personal' + TrustDomainCreateInferredSsid: + $ref: '#/components/examples/TrustDomainCreateInferredSsid' + TrustDomainCreateThreadStructured: + $ref: '#/components/examples/TrustDomainCreateThreadStructured' + TrustDomainCreateEphemeral: + $ref: '#/components/examples/TrustDomainCreateEphemeral' + TrustDomainCreateQoSPolicies: + $ref: '#/components/examples/TrustDomainCreateQoSPolicies' responses: - "200": - description: Contains information about networks at the service site + '201': + description: Trust Domain created successfully content: application/json: schema: - $ref: "#/components/schemas/NetworkList" + $ref: '#/components/schemas/TrustDomain' 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/Generic404" - "500": - $ref: "#/components/responses/Generic500" - "501": - $ref: "#/components/responses/Generic501" - "503": - $ref: "#/components/responses/Generic503" - - /devices: + TrustDomainResponseBasic: + $ref: '#/components/examples/TrustDomainResponseBasic' + TrustDomainResponseWiFiThread: + $ref: '#/components/examples/TrustDomainResponseWiFiThread' + '400': + $ref: '#/components/responses/Generic400' + '403': + $ref: '#/components/responses/Generic403' + '409': + $ref: '#/components/responses/Generic409' + '500': + $ref: '#/components/responses/Generic500' get: tags: - - Retrieve Device - summary: Get all devices + - Trust Domains + summary: Retrieves all Trust Domains visible to the calling API client security: - openId: - - network-access-management:devices:read - operationId: getDevices - description: | - Returns all devices. Scopes impact the output of this endpoint. See the examples for various permutations. - - **Required Scopes:** - - **one of** - - `network-access-management:devices:read` - - `network-access-management:devices:write` - - `network-access-management:devices.hardware-address:read` - - **Optional Scopes:** - - **one of** - - `network-access-management:service-sites:read` - - `network-access-management:service-sites.location:read` - - `network-access-management:isolated-networks:wifi:read` - - `network-access-management:isolated-networks:wifi:write` - - `network-access-management:isolated-networks:wifi.primary:read` - - `network-access-management:isolated-networks:wifi.primary:write` - - `network-access-management:isolated-networks:wifi.auxiliary:read` - - `network-access-management:isolated-networks:wifi.auxiliary:write` - responses: - "200": - description: Contains information about all devices - content: - application/json: - schema: - $ref: "#/components/schemas/DeviceList" - examples: - BaseDeviceList: - $ref: "#/components/examples/BaseDeviceList" - DeviceListWithHardwareAddress: - $ref: "#/components/examples/DeviceListWithHardwareAddress" - DeviceListWithServiceSite: - $ref: "#/components/examples/DeviceListWithServiceSite" - DeviceListWithNetworks: - $ref: "#/components/examples/DeviceListWithNetworks" - DeviceListWithHardwareAddressAndServiceSite: - $ref: "#/components/examples/DeviceListWithHardwareAddressAndServiceSite" - DeviceListWithHardwareAddressAndNetworks: - $ref: "#/components/examples/DeviceListWithHardwareAddressAndNetworks" - DeviceListWithServiceSiteAndNetworks: - $ref: "#/components/examples/DeviceListWithServiceSiteAndNetworks" - DeviceListWithHardwareAddressAndServiceSiteAndNetworks: - $ref: "#/components/examples/DeviceListWithHardwareAddressAndServiceSiteAndNetworks" - "401": - $ref: "#/components/responses/Generic401" - "403": - $ref: "#/components/responses/Generic403" - "500": - $ref: "#/components/responses/Generic500" - "501": - $ref: "#/components/responses/Generic501" - "503": - $ref: "#/components/responses/Generic503" - - /devices/{deviceId}: - get: - tags: - - Retrieve Device - summary: Get a device by ID - security: + - network-access-management:trust-domains - openId: - - network-access-management:devices:read - operationId: getDevice + - network-access-management:trust-domains:read-all + operationId: getTrustDomains description: | - Returns a device that matches the given ID. Scopes impact the output of this endpoint. See the examples for - various permutations. - - **Required Scopes:** - - **one of** - - `network-access-management:devices:read` - - `network-access-management:devices:write` - - `network-access-management:devices.hardware-address:read` + Retrieves all Trust Domains visible to the calling API client. - **Optional Scopes:** - - **one of** - - `network-access-management:service-sites:read` - - `network-access-management:service-sites.location:read` - - `network-access-management:isolated-networks:wifi:read` - - `network-access-management:isolated-networks:wifi:write` - - `network-access-management:isolated-networks:wifi.primary:read` - - `network-access-management:isolated-networks:wifi.primary:write` - - `network-access-management:isolated-networks:wifi.auxiliary:read` - - `network-access-management:isolated-networks:wifi.auxiliary:write` - parameters: - - $ref: "#/components/parameters/deviceId" + If the caller has `network-access-management:trust-domains`, the response is limited to + Trust Domains created by the caller. If the caller has `network-access-management:trust-domains:read-all`, + the response includes all Trust Domains associated with the subscriber. responses: - "200": - description: Contains information about the device + '200': + description: Contains information about all trust domains 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/Generic404" - "500": - $ref: "#/components/responses/Generic500" - "501": - $ref: "#/components/responses/Generic501" - "503": - $ref: "#/components/responses/Generic503" - - /devices/{deviceId}/isolated-networks: + type: array + items: + $ref: '#/components/schemas/TrustDomain' + '403': + $ref: '#/components/responses/Generic403' + '500': + $ref: '#/components/responses/Generic500' + '503': + $ref: '#/components/responses/Generic503' + /trust-domains/{trustDomainId}: + parameters: + - $ref: '#/components/parameters/trustDomainId' get: tags: - - Retrieve Isolated Network - summary: Get all networks configured on a device + - Trust Domains + summary: Get a specific Trust Domain security: - openId: - - network-access-management:devices:read - - network-access-management:isolated-networks:wifi:read - operationId: getNetworksByDevice + - network-access-management:trust-domains + - openId: + - network-access-management:trust-domains:read-all + operationId: getTrustDomain description: | - Returns all networks configured on a device that matches the given ID. Scopes impact the output of this - endpoint. See the examples for various permutations. - - **Required Scopes:** - - **all of** - - **one of** - - `network-access-management:devices:read` - - `network-access-management:devices:write` - - `network-access-management:devices.hardware-address:read` - - **one of** - - `network-access-management:isolated-networks:wifi:read` - - `network-access-management:isolated-networks:wifi:write` - - `network-access-management:isolated-networks:wifi.primary:read` - - `network-access-management:isolated-networks:wifi.primary:write` - - `network-access-management:isolated-networks:wifi.auxiliary:read` - - `network-access-management:isolated-networks:wifi.auxiliary:write` - parameters: - - $ref: "#/components/parameters/deviceId" + Retrieves the Trust Domain identified by the given ID. Visibility of this Trust Domain depends on the caller's scope and ownership: + - `trust-domains` restricts access to caller-owned Trust Domains. + - `trust-domains:read-all` allows retrieval of any Trust Domain associated with the subscriber. responses: - "200": - description: Contains information about networks configured on the device + '200': + description: Contains information about the specified trust domain content: application/json: schema: - $ref: "#/components/schemas/NetworkList" + $ref: '#/components/schemas/TrustDomain' 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/Generic404" - "500": - $ref: "#/components/responses/Generic500" - "501": - $ref: "#/components/responses/Generic501" - "503": - $ref: "#/components/responses/Generic503" - + TrustDomainResponseBasic: + $ref: '#/components/examples/TrustDomainResponseBasic' + '403': + $ref: '#/components/responses/Generic403' + '404': + $ref: '#/components/responses/Generic404' + '500': + $ref: '#/components/responses/Generic500' + '503': + $ref: '#/components/responses/Generic503' patch: tags: - - Configure and Apply Isolated Network - summary: Bulk insert, remove or replace many networks from the configuration of a device + - Trust Domains + summary: Update a specific Trust Domain security: - openId: - - network-access-management:devices:write - - network-access-management:isolated-networks:wifi:read - operationId: patchDeviceWithNetworks + - network-access-management:trust-domains + operationId: updateTrustDomain description: | - Bulk inserts, removes, or replaces many networks from the configuration of the device by the given IDs. - - The replace option is intended to be used for networks that have a "removable" flag of `false`. When a network - is replaced and is no longer assigned to any device, it is considered automatically deleted. - - **Required Scopes:** - - **all of** - - `network-access-management:devices:write` - - **one of** - - `network-access-management:isolated-networks:wifi:read` - - `network-access-management:isolated-networks:wifi:write` - - `network-access-management:isolated-networks:wifi.primary:read` - - `network-access-management:isolated-networks:wifi.primary:write` - - `network-access-management:isolated-networks:wifi.auxiliary:read` - - `network-access-management:isolated-networks:wifi.auxiliary:write` - parameters: - - $ref: "#/components/parameters/deviceId" + Updates the Trust Domain identified by the given ID. Any changes are automatically applied to all network access devices where the Trust Domain is configured. 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/Generic400" - "401": - $ref: "#/components/responses/Generic401" - "403": - $ref: "#/components/responses/Generic403" - "404": - $ref: "#/components/responses/Generic404" - "500": - $ref: "#/components/responses/Generic500" - "501": - $ref: "#/components/responses/Generic501" - "503": - $ref: "#/components/responses/Generic503" - - /isolated-networks: - get: - tags: - - Retrieve Isolated Network - summary: Get all Networks - security: - - openId: - - network-access-management:isolated-networks:wifi:read - operationId: getNetworks - description: | - Returns all networks. Scopes impact the output of this endpoint. See the examples for various permutations. - - ## With Default Device - **Required Scopes:** - - **one of** - - `network-access-management:isolated-networks:wifi:read` - - `network-access-management:isolated-networks:wifi:write` - - `network-access-management:isolated-networks:wifi.primary:read` - - `network-access-management:isolated-networks:wifi.primary:write` - - `network-access-management:isolated-networks:wifi.auxiliary:read` - - `network-access-management:isolated-networks:wifi.auxiliary:write` - - ## Without Default Device - **Required Scopes:** - - **all of** - - **one of** - - `network-access-management:isolated-networks:wifi:read` - - `network-access-management:isolated-networks:wifi:write` - - `network-access-management:isolated-networks:wifi.primary:read` - - `network-access-management:isolated-networks:wifi.primary:write` - - `network-access-management:isolated-networks:wifi.auxiliary:read` - - `network-access-management:isolated-networks:wifi.auxiliary:write` - - **one of** - - `network-access-management:devices:read` - - `network-access-management:devices:write` - - `network-access-management:devices.hardware-address:read` - responses: - "200": - description: Contains information about all networks - content: - application/json: - schema: - $ref: "#/components/schemas/NetworkList" - examples: - BaseNetworkList: - $ref: "#/components/examples/BaseNetworkList" - NetworkListWithDevices: - $ref: "#/components/examples/NetworkListWithDevices" - "401": - $ref: "#/components/responses/Generic401" - "403": - $ref: "#/components/responses/Generic403" - "500": - $ref: "#/components/responses/Generic500" - "503": - $ref: "#/components/responses/Generic503" - - post: - tags: - - Configure and Apply Isolated Network - summary: Create a new network - operationId: createNetwork - security: - - openId: - - network-access-management:isolated-networks:wifi:write - description: | - Creates and returns the new network. Scopes impact the function and output of this endpoint. See the examples - for various permutations. - - ## With Default Device - For eligible service owner's with a default device, create the network and configure it to the service owner's - one and only one device at their one and only one service location. The `devices` field MUST NOT be set or it - MUST be set to `undefined`. - - **Required Scopes:** - - **one of** - - `network-access-management:isolated-networks:wifi:write` - - `network-access-management:isolated-networks:wifi.primary:write` - - `network-access-management:isolated-networks:wifi.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:wifi:write` - - `network-access-management:isolated-networks:wifi.primary:write` - - `network-access-management:isolated-networks:wifi.auxiliary:write` - requestBody: + $ref: '#/components/schemas/TrustDomainUpdate' 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 + '200': + description: Contains information about the updated trust domain 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/Generic403" - "500": - $ref: "#/components/responses/Generic500" - "503": - $ref: "#/components/responses/Generic503" - - /isolated-networks/{netId}: - get: + $ref: '#/components/schemas/TrustDomain' + '400': + $ref: '#/components/responses/Generic400' + '403': + $ref: '#/components/responses/Generic403' + '404': + $ref: '#/components/responses/Generic404' + '500': + $ref: '#/components/responses/Generic500' + '503': + $ref: '#/components/responses/Generic503' + delete: tags: - - Retrieve Isolated Network - summary: Get a Network by ID + - Trust Domains + summary: Delete a specific Trust Domain security: - openId: - - network-access-management:isolated-networks:wifi:read - operationId: getNetwork + - network-access-management:trust-domains + operationId: deleteTrustDomain description: | - Returns the network that matches the given ID. Scopes impact the output of this endpoint. See the examples for - various permutations. - - ## With Default Device - **Required Scopes:** - - **one of** - - `network-access-management:isolated-networks:wifi:read` - - `network-access-management:isolated-networks:wifi:write` - - `network-access-management:isolated-networks:wifi.primary:read` - - `network-access-management:isolated-networks:wifi.primary:write` - - `network-access-management:isolated-networks:wifi.auxiliary:read` - - `network-access-management:isolated-networks:wifi.auxiliary:write` - - ## Without Default Device - **Required Scopes:** - - **all of** - - **one of** - - `network-access-management:isolated-networks:wifi:read` - - `network-access-management:isolated-networks:wifi:write` - - `network-access-management:isolated-networks:wifi.primary:read` - - `network-access-management:isolated-networks:wifi.primary:write` - - `network-access-management:isolated-networks:wifi.auxiliary:read` - - `network-access-management:isolated-networks:wifi.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" + Deletes the Trust Domain identified by the given ID and removes its configuration from all network access devices where it is applied. 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/Generic403" - "404": - $ref: "#/components/responses/Generic404" - "500": - $ref: "#/components/responses/Generic500" - "503": - $ref: "#/components/responses/Generic503" - - patch: + '204': + description: Trust Domain deleted successfully + '403': + $ref: '#/components/responses/Generic403' + '404': + $ref: '#/components/responses/Generic404' + '500': + $ref: '#/components/responses/Generic500' + '503': + $ref: '#/components/responses/Generic503' + /network-access-devices: + get: tags: - - Configure and Apply Isolated Network - summary: Update an existing network + - Reboot Requests + summary: Get all Network Access Devices associated with the service owner security: - openId: - - network-access-management:isolated-networks:wifi:write - operationId: updateNetwork + - network-access-management:reboot + operationId: getNetworkAccessDevices description: | - Updates the network, reconfigures any devices configured with the network, and returns the network that matches - the given ID. Scopes impact the output of this endpoint. See the examples for various permutations. - - ## With Default Device - **Required Scopes:** - - **one of** - - `network-access-management:isolated-networks:wifi:write` - - `network-access-management:isolated-networks:wifi.primary:write` - - `network-access-management:isolated-networks:wifi.auxiliary:write` - - ## Without Default Device - **Required Scopes:** - - **all of** - - `network-access-management:devices:write` - - **one of** - - `network-access-management:isolated-networks:wifi:write` - - `network-access-management:isolated-networks:wifi.primary:write` - - `network-access-management:isolated-networks:wifi.auxiliary:write` - parameters: - - $ref: "#/components/parameters/netId" - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/NetworkUpdate" - examples: - NetworkUpdate: - $ref: "#/components/examples/NetworkUpdate" + Retrieves all Network Access Devices associated with the subscriber that the caller is authorized to manage using the `network-access-management:reboot` scope. responses: - "200": - description: Contains information about the updated network + '200': + description: Contains the list of network access devices 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/Generic403" - "404": - $ref: "#/components/responses/Generic404" - "500": - $ref: "#/components/responses/Generic500" - "503": - $ref: "#/components/responses/Generic503" - - delete: - tags: - - Configure and Apply Isolated Network - summary: Delete a network - security: - - openId: - - network-access-management:isolated-networks:wifi:write - operationId: deleteNetwork - description: | - Deletes the network and removes the configuration from any devices configured with the network that matches the - given ID. - - ## With Default Device - **Required Scopes:** - - **one of** - - `network-access-management:isolated-networks:wifi:write` - - `network-access-management:isolated-networks:wifi.primary:write` - - `network-access-management:isolated-networks:wifi.auxiliary:write` - - ## Without Default Device - **Required Scopes:** - - **all off** - - `network-access-management:devices:write` - - **one of** - - `network-access-management:isolated-networks:wifi:write` - - `network-access-management:isolated-networks:wifi.primary:write` - - `network-access-management:isolated-networks:wifi.auxiliary:write` - parameters: - - $ref: "#/components/parameters/netId" - responses: - "204": - description: Successfully deleted the network - "400": - $ref: "#/components/responses/Generic400" - "401": - $ref: "#/components/responses/Generic401" - "403": - $ref: "#/components/responses/Generic403" - "404": - $ref: "#/components/responses/Generic404" - "500": - $ref: "#/components/responses/Generic500" - "503": - $ref: "#/components/responses/Generic503" - - /isolated-networks/{netId}/devices: + $ref: '#/components/schemas/NetworkAccessDeviceList' + '400': + $ref: '#/components/responses/Generic400' + '403': + $ref: '#/components/responses/Generic403' + '404': + $ref: '#/components/responses/Generic404' + '500': + $ref: '#/components/responses/Generic500' + '503': + $ref: '#/components/responses/Generic503' + /network-access-devices/{networkAccessDeviceId}: get: tags: - - Retrieve Device - summary: Get all devices configured with a network + - Reboot Requests + summary: Get a specific Network Access Device security: - openId: - - network-access-management:devices:read - - network-access-management:isolated-networks:wifi:read - operationId: getDevicesByNetwork + - network-access-management:reboot + operationId: getNetworkAccessDevice description: | - Returns all devices configured with a network that matches the given ID. Scopes impact the output of this - endpoint. See the examples for various permutations. - - **Required Scopes:** - - **all of** - - **one of** - - `network-access-management:devices:read` - - `network-access-management:devices:write` - - `network-access-management:devices.hardware-address:read` - - **one of** - - `network-access-management:isolated-networks:wifi:read` - - `network-access-management:isolated-networks:wifi:write` - - `network-access-management:isolated-networks:wifi.primary:read` - - `network-access-management:isolated-networks:wifi.primary:write` - - `network-access-management:isolated-networks:wifi.auxiliary:read` - - `network-access-management:isolated-networks:wifi.auxiliary:write` - - **Optional Scopes:** - - **one of** - - `network-access-management:service-sites:read` - - `network-access-management:service-sites.location:read` + Retrieves the Network Access Device that matches the given ID. parameters: - - $ref: "#/components/parameters/netId" + - $ref: '#/components/parameters/networkAccessDeviceId' responses: - "200": - description: Contains information about devices configured with the network + '200': + description: Contains information about the specified network access device 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/Generic404" - "500": - $ref: "#/components/responses/Generic500" - "501": - $ref: "#/components/responses/Generic501" - "503": - $ref: "#/components/responses/Generic503" - - patch: + $ref: '#/components/schemas/NetworkAccessDevice' + '400': + $ref: '#/components/responses/Generic400' + '403': + $ref: '#/components/responses/Generic403' + '404': + $ref: '#/components/responses/Generic404' + '500': + $ref: '#/components/responses/Generic500' + '503': + $ref: '#/components/responses/Generic503' + /reboot-requests: + post: tags: - - Configure and Apply Isolated Network - summary: Bulk insert, remove, or replace a network from the configuration of many devices + - Reboot Requests + summary: Create a new Reboot Request security: - openId: - - network-access-management:devices:write - - network-access-management:isolated-networks:wifi:read - operationId: patchDevicesWithNetwork + - network-access-management:reboot description: | - Bulk inserts, removes, replaces a network from the configuration of many devices by the given IDs. - - **Required Scopes:** - - **all of ** - - `network-access-management:devices:write` - - **one of** - - `network-access-management:isolated-networks:wifi:read` - - `network-access-management:isolated-networks:wifi:write` - - `network-access-management:isolated-networks:wifi.primary:read` - - `network-access-management:isolated-networks:wifi.primary:write` - - `network-access-management:isolated-networks:wifi.auxiliary:read` - - `network-access-management:isolated-networks:wifi.auxiliary:write` - parameters: - - $ref: "#/components/parameters/netId" + Creates a new Reboot Request targeting one or more Network Access Devices. + operationId: createRebootRequest requestBody: + description: | + Creates a reboot request for one or more network access devices. Supports two targeting modes: + + Targeting modes: + - Inferred (implicit/default device): Omit the 'devices' array to request a reboot of the single + default device associated with the subscriber context. This is only valid when exactly one + device is eligible. If no default device exists or multiple devices are provisioned, the + request MUST be rejected (e.g. 400 INVALID_ARGUMENT or 422 MISSING_IDENTIFIER). + - Explicit (targeted devices): Provide a 'devices' array of one or more device UUIDs to request + reboots on those specific devices. Validation MUST fail if any supplied device ID is unknown, + not reboot-capable, or the caller lacks authorization. + + Scheduling: + - Immediate reboot: Omit 'atTime'. + - Scheduled reboot: Include 'atTime' (RFC 3339 with timezone). Time MUST be in the future; past + values SHOULD produce a 400 OUT_OF_RANGE error. + + Idempotency / duplication: + - Multiple identical pending reboot requests (same device set and same atTime) MAY be rejected + with 409 CONFLICT or collapsed by implementation. + + Error conditions (examples): + - 400 INVALID_ARGUMENT: Unsupported time format, too many device IDs, malformed UUID. + - 404 IDENTIFIER_NOT_FOUND: One or more device IDs not found. + - 403 PERMISSION_DENIED: Caller lacks scope or device ownership. + - 409 CONFLICT: Reboot already scheduled for the same devices and time. + - 422 MISSING_IDENTIFIER (implementation-specific): 'devices' omitted but no default device. + + Behavioral guarantees: + - If 'devices' omitted and inference succeeds, the response MUST reflect the resolved device list. + - If any device fails validation, no reboot request is created (atomic failure). + - Partial success is NOT permitted. 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/Generic400" - "401": - $ref: "#/components/responses/Generic401" - "403": - $ref: "#/components/responses/Generic403" - "404": - $ref: "#/components/responses/Generic404" - "500": - $ref: "#/components/responses/Generic500" - "501": - $ref: "#/components/responses/Generic501" - "503": - $ref: "#/components/responses/Generic503" - - /reboot-requests: - get: - tags: - - Retrieve Reboot Request - summary: Get all Reboot Requests - security: - - openId: - - network-access-management:reboot-requests:read - operationId: getRebootRequests - description: | - Returns all reboot requests. Scopes impact the output of this endpoint. See the examples for various - permutations. - - ## With Default Device - **Required Scopes:** - - **one of** - - `network-access-management:reboot-requests:read` - - `network-access-management:reboot-requests:write` - - ## Without Default Device - **Required Scopes:** - - **all of** - - **one of** - - `network-access-management:reboot-requests:read` - - `network-access-management:reboot-requests:write` - - **one of** - - `network-access-management:devices:read` - - `network-access-management:devices:write` - - `network-access-management:devices.hardware-address:read` + $ref: '#/components/schemas/RebootRequestCreate' + examples: + RebootRequestCreateImmediate: + $ref: '#/components/examples/RebootRequestCreateImmediateDefaultDevice' + RebootRequestCreateScheduled: + $ref: '#/components/examples/RebootRequestCreateScheduledMultipleDevices' responses: - "200": - description: Contains information about all reboot requests + '201': + description: Reboot Request created successfully 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/Generic403" - "500": - $ref: "#/components/responses/Generic500" - "501": - $ref: "#/components/responses/Generic501" - "503": - $ref: "#/components/responses/Generic503" - - post: + $ref: '#/components/schemas/RebootRequest' + '400': + $ref: '#/components/responses/Generic400' + '403': + $ref: '#/components/responses/Generic403' + '404': + $ref: '#/components/responses/Generic404' + '409': + $ref: '#/components/responses/Generic409' + '422': + $ref: '#/components/responses/Generic422' + '500': + $ref: '#/components/responses/Generic500' + get: tags: - - Configure Reboot Requests - summary: Create a new reboot request + - Reboot Requests + summary: Get all Reboot Requests created by the calling API client security: - openId: - - network-access-management:reboot-requests:write - operationId: createRebootRequest + - network-access-management:reboot + operationId: getRebootRequests description: | - Creates and returns the new reboot request. Scopes impact the function and output of this endpoint. See the - examples for various permutations. - - ## With Default Device - Creates the reboot request and issues it to the service owner's one and only one device at their one and only - one service location. The `devices` field MUST NOT be set or it MUST be set to `undefined`. - - **Required Scopes:** - - **all of** - - `network-access-management:reboot-requests:write` - - ## Without Default Device - Creates the reboot request and issues it to one or more devices. The `devices` field MUST be set to a non-empty - `list of device IDs`. - - **Required Scopes:** - - **all of** - - `network-access-management:devices:write` - - `network-access-management:reboot-requests:write` - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/RebootRequestCreate" - examples: - BaseRebootRequestCreate: - $ref: "#/components/examples/BaseRebootRequestCreate" - RebootRequestCreateWithDevices: - $ref: "#/components/examples/RebootRequestCreateWithDevices" + This endpoint returns a list of Reboot Requests associated with the service owner created by the calling API client. responses: - "201": - description: Contains information about the created reboot request + '200': + description: Contains information about all reboot requests 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/Generic403" - "500": - $ref: "#/components/responses/Generic500" - "501": - $ref: "#/components/responses/Generic501" - "503": - $ref: "#/components/responses/Generic503" - - /reboot-requests/{rebootId}: + type: array + items: + $ref: '#/components/schemas/RebootRequest' + '400': + $ref: '#/components/responses/Generic400' + '403': + $ref: '#/components/responses/Generic403' + '500': + $ref: '#/components/responses/Generic500' + /reboot-requests/{rebootRequestId}: + parameters: + - $ref: '#/components/parameters/rebootRequestId' get: tags: - - Retrieve Reboot Request - summary: Get a Reboot Request by ID + - Reboot Requests + summary: Get a specific Reboot Request security: - openId: - - network-access-management:reboot-requests:read + - network-access-management:reboot operationId: getRebootRequest description: | - Returns the reboot request that matches the given ID. Scopes impact the output of this endpoint. See the - examples for various permutations. - - ## With Default Device - **Required Scopes:** - - **one of** - - `network-access-management:reboot-requests:read` - - `network-access-management:reboot-requests:write` - - ## Without Default Device - **Required Scopes:** - - **all off** - - **one of** - - `network-access-management:reboot-requests:read` - - `network-access-management:reboot-requests:write` - - **one of** - - `network-access-management:devices:read` - - `network-access-management:devices:write` - - `network-access-management:devices.hardware-address:read` - parameters: - - $ref: "#/components/parameters/rebootId" + Retrieves the Reboot Request that matches the given ID. responses: - "200": - description: Contains information about the reboot request + '200': + description: Contains information about the specified 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/Generic403" - "404": - $ref: "#/components/responses/Generic404" - "500": - $ref: "#/components/responses/Generic500" - "501": - $ref: "#/components/responses/Generic501" - "503": - $ref: "#/components/responses/Generic503" - + $ref: '#/components/schemas/RebootRequest' + '400': + $ref: '#/components/responses/Generic400' + '403': + $ref: '#/components/responses/Generic403' + '404': + $ref: '#/components/responses/Generic404' + '500': + $ref: '#/components/responses/Generic500' patch: tags: - - Configure Reboot Requests - summary: Update an existing reboot request + - Reboot Requests + summary: Update an existing Reboot Request security: - openId: - - network-access-management:reboot-requests:write - operationId: updateRebootRequest + - network-access-management:reboot description: | - Updates the reboot request, reboot for any devices targeted with the reboot request, and returns the reboot - request that matches the given ID. Scopes impact the output of this endpoint. See the examples for various - permutations. - - ## With Default Device - **Required Scopes:** - - **all of** - - `network-access-management:reboot-requests:write` - - ## Without Default Device - **Required Scopes:** - - **all of** - - `network-access-management:devices:write` - - `network-access-management:reboot-requests:write` - parameters: - - $ref: "#/components/parameters/rebootId" + Updates an existing Reboot Request to modify its scheduled time or cancel it. + operationId: updateRebootRequest requestBody: - required: true content: application/json: schema: - $ref: "#/components/schemas/RebootRequestUpdate" - examples: - RebootRequestUpdate: - $ref: "#/components/examples/RebootRequestUpdate" + $ref: '#/components/schemas/RebootRequestUpdate' + required: true responses: - "200": - description: Contains information about the updated reboot request + '200': + description: Reboot Request updated successfully 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/Generic403" - "404": - $ref: "#/components/responses/Generic404" - "500": - $ref: "#/components/responses/Generic500" - "501": - $ref: "#/components/responses/Generic501" - "503": - $ref: "#/components/responses/Generic503" - + $ref: '#/components/schemas/RebootRequest' + '400': + $ref: '#/components/responses/Generic400' + '403': + $ref: '#/components/responses/Generic403' + '404': + $ref: '#/components/responses/Generic404' + '409': + $ref: '#/components/responses/Generic409' + '422': + $ref: '#/components/responses/Generic422' + '500': + $ref: '#/components/responses/Generic500' delete: tags: - - Configure Reboot Requests - summary: Delete a reboot request + - Reboot Requests + summary: Delete an existing Reboot Request security: - openId: - - network-access-management:reboot-requests:write - operationId: deleteRebootRequest + - network-access-management:reboot description: | - Deletes the reboot request that matches the given ID. - - ## With Default Device - **Required Scopes:** - - **all of** - - `network-access-management:reboot-requests:write` - - ## Without Default Device - **Required Scopes:** - - **all of** - - `network-access-management:devices:write` - - `network-access-management:reboot-requests:write` - parameters: - - $ref: "#/components/parameters/rebootId" + Deletes an existing Reboot Request, cancelling the scheduled reboot if it has not yet occurred. + operationId: deleteRebootRequest responses: - "204": - description: Successfully deleted the reboot request - "400": - $ref: "#/components/responses/Generic400" - "401": - $ref: "#/components/responses/Generic401" - "403": - $ref: "#/components/responses/Generic403" - "404": - $ref: "#/components/responses/Generic404" - "500": - $ref: "#/components/responses/Generic500" - "501": - $ref: "#/components/responses/Generic501" - "503": - $ref: "#/components/responses/Generic503" - + '204': + description: Reboot Request deleted successfully + '400': + $ref: '#/components/responses/Generic400' + '403': + $ref: '#/components/responses/Generic403' + '404': + $ref: '#/components/responses/Generic404' + '500': + $ref: '#/components/responses/Generic500' components: securitySchemes: openId: type: openIdConnect - description: OpenID Connect + description: | + OpenID Connect authentication with scope-based authorization. + + **Resource Isolation:** + Unless otherwise specified, all scopes only grant access to resources + (e.g., Trust Domains, Reboot Requests) created by the same API client. + API clients cannot access or modify resources created by other API clients + unless the `:read-all` or `:admin` scope variants are explicitly granted. + + **Scope Model:** + This API uses a simplified scope model to balance clarity with flexibility. + Functional authorization (e.g., managing Trust Domains) is handled by scopes, + while ownership enforcement is handled by the API provider. + + **Available Scopes:** + - `network-access-management:trust-domains` — Full management of Trust Domains created by the calling API client + (includes create, read, modify, and delete actions). + - `network-access-management:trust-domains:read-all` — Read-only access to all Trust Domains + associated with the same subscriber, including those created by other API clients. + Intended for use cases involving federated discovery or configuration replication. + - `network-access-management:reboot` — Create, list, and manage Reboot Requests for network + access devices owned by or delegated to the calling API client. openIdConnectUrl: https://example.com/.well-known/openid-configuration + schemas: + UUID: + type: string + format: uuid + pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ + minLength: 36 + maxLength: 36 + description: | + A universally unique identifier (UUID) as defined by RFC 4122. + Must be a valid UUID format with proper version (1-5) and variant bits. + Only lowercase hexadecimal characters are accepted for consistency. + example: 550e8400-e29b-41d4-a716-446655440000 + ServiceId: + allOf: + - $ref: '#/components/schemas/UUID' + description: | + A unique identifier that represents a service account associated with this resource. - headers: - x-correlator: - description: Correlation id for the different services - schema: - $ref: "#/components/schemas/XCorrelator" - - parameters: - x-correlator: - name: x-correlator - in: header - description: Correlation id for the different services - schema: - $ref: "#/components/schemas/XCorrelator" - - 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: - XCorrelator: - type: string - pattern: ^[a-zA-Z0-9-_:;.\/<>{}]{0,256}$ - example: "b4333c46-49c0-4f62-80d7-f0ef930f1c46" - - 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" - - ErrorInfo: - type: object - required: - - message - - status - - code - properties: - message: - type: string - description: A human readable description of what the event represent - status: - type: integer - description: HTTP response status code - code: - type: string - description: Friendly Code to describe the error - - 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" - - Point: - type: object - description: Coordinates (latitude, longitude) defining a location in a map - required: - - latitude - - longitude - properties: - latitude: - $ref: "#/components/schemas/Latitude" - longitude: - $ref: "#/components/schemas/Longitude" - example: &point - latitude: 50.735851 - longitude: 7.10066 - + Must be a valid UUID as defined by RFC 4122 (versions 1-5) using only lowercase hexadecimal characters. Latitude: description: Latitude component of a location type: number format: double minimum: -90 maximum: 90 - Longitude: description: Longitude component of location type: number format: double minimum: -180 maximum: 180 - + Point: + type: object + description: Coordinates (latitude, longitude) defining a location in a map + required: + - latitude + - longitude + properties: + latitude: + $ref: '#/components/schemas/Latitude' + longitude: + $ref: '#/components/schemas/Longitude' + example: + latitude: 50.735851 + longitude: 7.10066 PropertyAddress: type: object + description: Represents a physical property address following TMF673 Geographic Address Management API specification. 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/ @@ -1495,513 +782,655 @@ components: description: The unique identifier for the property address minLength: 1 maxLength: 64 - example: &property-address-id "address-123" + example: address-123 addressLine1: type: string maxLength: 128 description: The first line of the address - example: &property-address-address-line-1 "123 Main St" + example: 123 Main St addressLine2: type: string maxLength: 128 description: The second line of the address - example: &property-address-address-line-2 "Suite 456" + example: Suite 456 streetNr: type: string maxLength: 64 description: The street number - example: &property-address-street-nr "123" + example: '123' streetNrSuffix: type: string maxLength: 64 description: The suffix for the street number - example: &property-address-street-nr-suffix "A" + example: A streetNrLast: type: string maxLength: 64 description: The last street number - example: &property-address-street-nr-last "125" + example: '125' streetNrLastSuffix: type: string maxLength: 64 description: The suffix for the last street number - example: &property-address-street-nr-last-suffix "B" + example: B streetName: type: string maxLength: 64 description: The name of the street - example: &property-address-street-name "Main" + example: Main subUnitType: type: string maxLength: 64 description: The type of sub-unit (e.g., Apartment, Suite) - example: &property-address-sub-unit-type "Apartment" + example: Apartment subUnitNr: type: string maxLength: 64 description: The number of the sub-unit - example: &property-address-sub-unit-nr "A12" + example: A12 levelType: type: string maxLength: 64 description: The type of level (e.g., Floor, Basement) - example: &property-address-level-type "Floor" + example: Floor levelNr: type: string maxLength: 64 description: The number of the level - example: &property-address-level-nr "3" + example: '3' buildingName: type: string maxLength: 64 description: The name of the building - example: &property-address-building-name "Example Building" + example: Example Building privateStreetName: type: string maxLength: 64 description: The name of a private street - example: &property-address-private-street-name "Private Rd" + example: Private Rd locality: type: string maxLength: 64 description: The locality (neighborhood, area) - example: &property-address-locality "Example Locality" + example: Example Locality city: type: string maxLength: 128 description: The city or town - example: &property-address-city "Example State" + example: Example State stateOrProvince: type: string maxLength: 64 description: The state or province - example: &property-address-state-or-province "EX" + example: EX country: type: string maxLength: 64 description: The country - example: &property-address-country "United States" + example: United States postCode: type: string maxLength: 64 description: The postal code or ZIP code - example: &property-address-post-code "12345" + example: '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 - + example: '6789' + example: + id: address-123 + addressLine1: 123 Main St + addressLine2: Suite 456 + streetNr: '123' + streetNrSuffix: A + streetNrLast: '125' + streetNrLastSuffix: B + streetName: Main + subUnitType: Apartment + subUnitNr: A12 + levelType: Floor + levelNr: '3' + buildingName: Example Building + privateStreetName: Private Rd + locality: Example Locality + city: Example State + stateOrProvince: EX + country: United States + postCode: '12345' + postCodeExtension: '6789' ServiceSite: type: object + description: A Service Site represents a subscriber location associated with one or more Network Access Devices. Implementations MAY provide geographic coordinates, postal address data, or both, depending on local regulatory and operational requirements. properties: id: - $ref: "#/components/schemas/ServiceSiteId" + allOf: + - $ref: '#/components/schemas/UUID' + readOnly: true name: type: string + description: The name of the service site. maxLength: 64 - example: &service-site-name "Example Service Site 1" + example: Example Service Site 1 description: type: string + description: A textual description of the service site. 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" + example: This is the first example service site location: type: object + description: Geographic location information for the service site, including coordinates and/or property address. properties: geographicPoint: - $ref: "#/components/schemas/Point" + $ref: '#/components/schemas/Point' propertyAddress: - $ref: "#/components/schemas/PropertyAddress" - example: &service-site-location - geographicPoint: *point - propertyAddress: *property-address + $ref: '#/components/schemas/PropertyAddress' + example: + geographicPoint: + latitude: 50.735851 + longitude: 7.10066 + propertyAddress: + id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 + addressLine1: 123 Main St + addressLine2: Suite 456 + streetNr: '123' + streetNrSuffix: A + streetNrLast: '125' + streetNrLastSuffix: B + streetName: Main + subUnitType: Apartment + subUnitNr: A12 + levelType: Floor + levelNr: '3' + buildingName: Sunset Towers + privateStreetName: Private Rd + locality: Example Locality + city: Example State + stateOrProvince: EX + country: United States + postCode: '12345' + postCodeExtension: '6789' 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: + example: + id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 + name: Example Service Site 1 + description: This is the first example service site + location: + geographicPoint: + latitude: 50.735851 + longitude: 7.10066 + propertyAddress: + id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 + addressLine1: 123 Main St + addressLine2: Suite 456 + streetNr: '123' + streetNrSuffix: A + streetNrLast: '125' + streetNrLastSuffix: B + streetName: Main + subUnitType: Apartment + subUnitNr: A12 + levelType: Floor + levelNr: '3' + buildingName: Sunset Towers + privateStreetName: Private Rd + locality: Example Locality + city: Example State + stateOrProvince: EX + country: United States + postCode: '12345' + postCodeExtension: '6789' + Service: + type: object + description: | + A service represents a logical commercial subscription or account relationship + between a network operator and a subscriber. This may correspond to residential, + commercial, public Wi-Fi, or other service types. + properties: + id: + $ref: '#/components/schemas/ServiceId' + name: + type: string + maxLength: 64 + description: Optional friendly name for the service + example: Main Home Internet + description: + type: string + maxLength: 255 + description: Optional description of the service + example: Internet subscription for primary residence + serviceSite: + $ref: '#/components/schemas/ServiceSite' + required: + - id + example: + id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 + name: Main Home Internet + description: Internet subscription for primary residence + serviceSite: + id: 123e4567-e89b-12d3-a456-426614174000 + name: Primary Residence + description: 123 Main Street + ServiceList: type: array + description: A list of services accessible to the calling identity 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 - point: - latitude: 41.8781 - longitude: -87.6298 - 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. + $ref: '#/components/schemas/Service' + example: + - id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 + name: Main Home Internet + description: Internet subscription for primary residence + serviceSite: + id: 123e4567-e89b-12d3-a456-426614174000 + name: Primary Residence + description: 123 Main Street + - id: 123e4567-e89b-12d3-a456-426614174001 + name: Vacation Home Internet + description: Internet subscription for vacation home + XCorrelator: type: string - enum: [primary, auxiliary] - default: "auxiliary" - example: &network-role "primary" - - NetworkDeviceConfiguration: + pattern: ^[a-zA-Z0-9-_:;.\/<>{}]{0,256}$ + example: b4333c46-49c0-4f62-80d7-f0ef930f1c46 + ErrorInfo: type: object - description: >- - A specific network configuration with an implied network to configure on a specific network access device with - specified role. + required: + - status + - code + - message properties: - device: - description: "ID of the device with the network" - allOf: - - $ref: "#/components/schemas/DeviceId" - - example: *device-id - role: - description: >- - Role of the network on the device. Defaults to "auxiliary" if unspecified. - default: "auxiliary" - allOf: - - $ref: "#/components/schemas/NetworkRole" - - example: *network-role - required: ["device"] - example: &network-device-configuration - device: *device-id - role: *network-role - - NetworkDeviceReplacement: + status: + type: integer + description: HTTP response status code + code: + type: string + description: A human-readable code to describe the error + message: + type: string + description: A human-readable description of what the event represents + PasswordConstraints: 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: + minLength: + type: integer + minimum: 8 + description: Minimum password length + example: 8 + maxLength: + type: integer + minimum: 1 + description: Maximum password length + example: 63 + requireSpecialCharacters: + type: boolean + description: Whether special characters are required + example: false + required: + - minLength + - maxLength + description: Password validation constraints + WiFiAccessTypeProperties: + type: object + properties: + ssidRequired: + type: boolean + description: Whether SSID must be provided (false if can be inferred) + example: true + supportedSecurityModes: + type: array + items: + type: string + enum: + - WPA2-Personal + - WPA3-Personal + - WPA2-WPA3-Personal + - WPA2-Enterprise + - WPA3-Enterprise + description: Supported Wi-Fi security mode types + example: + - WPA2-Personal + - WPA3-Personal + passwordConstraints: + $ref: '#/components/schemas/PasswordConstraints' + authServerRequired: + type: boolean + description: Whether authentication server must be specified for Enterprise modes + example: false + description: Wi-Fi specific access type properties + SupportedWiFiWpaPersonalAccessType: type: object - description: | - Properties of a specific network configuration with an implied network on a specific network access device. properties: - intersectionType: + accessType: type: string - enum: ["NetworkDeviceRoleConfiguration", "NetworkDeviceReplacement"] - example: &network-device-intersection-type "NetworkDeviceRoleConfiguration" + description: The type of network access. + enum: + - Wi-Fi:WPA_PERSONAL + example: Wi-Fi:WPA_PERSONAL + wifiProperties: + $ref: '#/components/schemas/WiFiAccessTypeProperties' required: - - intersectionType - discriminator: - propertyName: intersectionType - mappings: - - NetworkDeviceRoleConfiguration: "#/components/schemas/NetworkDeviceRoleConfiguration" - - NetworkDeviceReplacement: "#/components/schemas/NetworkDeviceReplacement" - example: &network-device-intersection-create - intersectionType: *network-device-intersection-type - device: *device-id - role: *network-role - - NetworkDeviceIntersectionCreateList: - type: array - items: - $ref: "#/components/schemas/NetworkDeviceIntersectionCreate" - example: &network-device-intersection-create-list - - *network-device-intersection-create - - &network-device-intersection-create-2 - intersectionType: &network-device-intersection-type-2 "NetworkDeviceReplacement" - device: *device-id2 - replace: *network-id2 - - NetworkDeviceIntersection: - allOf: - - $ref: "#/components/schemas/NetworkDeviceConfiguration" - - description: >- - Properties of a specific network configuration with an implied network on a specific network access device. + - accessType + - wifiProperties + description: Wi-Fi WPA Personal access type capabilities + SupportedWiFiWpaEnterpriseAccessType: + type: object + properties: + accessType: + type: string + description: The type of network access. + enum: + - Wi-Fi:WPA_ENTERPRISE + example: Wi-Fi:WPA_ENTERPRISE + wifiProperties: + $ref: '#/components/schemas/WiFiAccessTypeProperties' + required: + - accessType + - wifiProperties + description: Wi-Fi WPA Enterprise access type capabilities + ThreadAccessTypeProperties: + type: object + properties: + supportedChannels: + type: object properties: - removable: - type: boolean - description: >- - Flag indicating if the network can be removed. Defaults to `true` if unspecified. - default: true - example: &network-removable false + min: + type: integer + minimum: 11 + maximum: 26 + description: Minimum supported Thread channel + example: 11 + max: + type: integer + minimum: 11 + maximum: 26 + description: Maximum supported Thread channel + example: 26 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: + - min + - max + description: Range of supported Thread channels + networkKeyFormat: + type: string + enum: + - 32-hex-digits + description: Required format for Thread network keys + example: 32-hex-digits + networkNameConstraints: + type: object + properties: + minLength: + type: integer + minimum: 1 + example: 1 + maxLength: + type: integer + minimum: 1 + example: 16 + required: + - minLength + - maxLength + description: Constraints on Thread network names + maxDatasetLength: + type: integer + minimum: 1 + description: Maximum length for TLV operational dataset (applies to Thread:TLV) + example: 255 + description: Thread specific access type properties + SupportedThreadStructuredAccessType: 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" + accessType: + type: string + description: The type of network access. + enum: + - Thread:STRUCTURED + example: Thread:STRUCTURED + threadProperties: + $ref: '#/components/schemas/ThreadAccessTypeProperties' + required: + - accessType + - threadProperties + description: Thread structured access type capabilities + SupportedThreadTlvAccessType: + type: object + properties: + accessType: + type: string + description: The type of network access. + enum: + - Thread:TLV + example: Thread:TLV + threadProperties: + $ref: '#/components/schemas/ThreadAccessTypeProperties' + required: + - accessType + - threadProperties + description: Thread TLV access type capabilities + SupportedAccessType: + type: object + description: Access type capabilities with discriminated properties based on accessType. Represents the configuration options supported by the API provider for a given access type. This is distinct from AccessDetail, which represents the configuration requested by an API client. + properties: + accessType: + type: string + enum: + - Wi-Fi:WPA_PERSONAL + - Wi-Fi:WPA_ENTERPRISE + - Thread:STRUCTURED + - Thread:TLV + description: The supported access type identifier (must match POST endpoint values) + oneOf: + - $ref: '#/components/schemas/SupportedWiFiWpaPersonalAccessType' + - $ref: '#/components/schemas/SupportedWiFiWpaEnterpriseAccessType' + - $ref: '#/components/schemas/SupportedThreadStructuredAccessType' + - $ref: '#/components/schemas/SupportedThreadTlvAccessType' + discriminator: + propertyName: accessType + mapping: + Wi-Fi:WPA_PERSONAL: '#/components/schemas/SupportedWiFiWpaPersonalAccessType' + Wi-Fi:WPA_ENTERPRISE: '#/components/schemas/SupportedWiFiWpaEnterpriseAccessType' + Thread:STRUCTURED: '#/components/schemas/SupportedThreadStructuredAccessType' + Thread:TLV: '#/components/schemas/SupportedThreadTlvAccessType' + required: + - accessType + MaxDevicesPolicyCapability: + type: object + properties: + maxValue: + type: integer + minimum: 1 + description: Maximum number of devices allowed + example: 100 + minValue: + type: integer + minimum: 1 + description: Minimum number of devices allowed + example: 1 + required: + - maxValue + - minValue + description: Capabilities for maximum devices policy + BandwidthPolicyCapability: + type: object + properties: + maxValue: + type: integer + minimum: 1 + description: Maximum bandwidth value in bits per second + example: 1000000000 + minValue: + type: integer + minimum: 1 + description: Minimum bandwidth value in bits per second + example: 1000000 + required: + - maxValue + - minValue + description: Capabilities for bandwidth control policies + EgressPolicyCapability: + type: object + properties: + maxEntries: + type: integer + minimum: 1 + description: Maximum number of allowed egress destinations + example: 50 + supportedDestinationTypes: + type: array + items: + type: string + enum: + - IP + - FQDN + - CIDR + description: Supported destination address formats + example: + - IP + - FQDN + - CIDR + required: + - maxEntries + - supportedDestinationTypes + description: Capabilities for egress allowed list policy + TrustDomainCapabilities: + type: object + properties: + supportedAccessTypes: + type: array + description: List of supported access types and their variants + items: + $ref: '#/components/schemas/SupportedAccessType' + minItems: 1 + supportedPolicies: + type: object + description: Map of supported policy types to their capability details + properties: + maxDevices: + $ref: '#/components/schemas/MaxDevicesPolicyCapability' + maxDomainDownstreamRate: + $ref: '#/components/schemas/BandwidthPolicyCapability' + maxDomainUpstreamRate: + $ref: '#/components/schemas/BandwidthPolicyCapability' + egressAllowedList: + $ref: '#/components/schemas/EgressPolicyCapability' + example: + maxDevices: + maxValue: 100 + minValue: 1 + maxDomainDownstreamRate: + maxValue: 1000000000 + minValue: 1000000 + required: + - supportedAccessTypes + description: Describes the Trust Domain configuration capabilities supported by this API provider + ResourceIdentifier: + type: object + properties: + id: 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 + - $ref: '#/components/schemas/UUID' + readOnly: true 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 - - PhoneNumber: - description: A public identifier addressing a telephone subscription. In mobile networks it corresponds to the MSISDN (Mobile Station International Subscriber Directory Number). In order to be globally unique it has to be formatted in international format, according to E.164 standard, prefixed with '+'. - type: string - pattern: '^\+[1-9][0-9]{4,14}$' - example: "+123456789" - - NetworkAccessIdentifier: - description: A public identifier addressing a subscription in a mobile network. In 3GPP terminology, it corresponds to the GPSI formatted with the External Identifier ({Local Identifier}@{Domain Identifier}). Unlike the telephone number, the network access identifier is not subjected to portability ruling in force, and is individually managed by each operator. + - id + description: A generic schema for resources identified by a unique ID. + DateTime: type: string - example: "123456789@domain.com" - - DeviceIpv4Addr: - type: object + format: date-time description: | - The device should be identified by either the public (observed) IP address and port as seen by the application server, or the private (local) and any public (observed) IP addresses in use by the device (this information can be obtained by various means, for example from some DNS servers). - - If the allocated and observed IP addresses are the same (i.e. NAT is not in use) then the same address should be specified for both publicAddress and privateAddress. - - If NAT64 is in use, the device should be identified by its publicAddress and publicPort, or separately by its allocated IPv6 address (field ipv6Address of the Device object) - - In all cases, publicAddress must be specified, along with at least one of either privateAddress or publicPort, dependent upon which is known. In general, mobile devices cannot be identified by their public IPv4 address alone. + 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: '2023-07-03T14:27:08.312+02:00' + MaxDevicesPolicy: + type: integer + minimum: 1 + description: Limits the number of devices that may join the Trust Domain. + example: 10 + MaxDomainDownstreamRatePolicy: + type: object properties: - publicAddress: - $ref: "#/components/schemas/SingleIpv4Addr" - privateAddress: - $ref: "#/components/schemas/SingleIpv4Addr" - publicPort: - $ref: "#/components/schemas/Port" - anyOf: - - required: [publicAddress, privateAddress] - - required: [publicAddress, publicPort] + value: + type: integer + description: Maximum downstream throughput across the domain. + unit: + type: string + enum: + - Kbps + - Mbps + - Gbps + description: Unit of measurement for downstream throughput. + required: + - value + - unit + description: Maximum downstream throughput policy across the Trust Domain. example: - publicAddress: "84.125.93.10" - publicPort: 59765 - - SingleIpv4Addr: - description: A single IPv4 address with no subnet mask - type: string - format: ipv4 - example: "84.125.93.10" - - Port: - description: TCP or UDP port number - type: integer - minimum: 0 - maximum: 65535 - - DeviceIpv6Address: - description: | - The device should be identified by the observed IPv6 address, or by any single IPv6 address from within the subnet allocated to the device (e.g. adding ::0 to the /64 prefix). - type: string - format: ipv6 - example: 2001:db8:85a3:8d3:1319:8a2e:370:7344 - - # https://github.com/camaraproject/Commonalities/blob/main/artifacts/CAMARA_common.yaml - BaseDevice: - description: | - End-user equipment able to connect to a mobile network. Examples of devices include smartphones or IoT sensors/actuators. - The developer can choose to provide the below specified device identifiers: - * `ipv4Address` - * `ipv6Address` - * `phoneNumber` - * `networkAccessIdentifier` - NOTE1: the network operator might support only a subset of these options. The API invoker can provide multiple identifiers to be compatible across different network operators. In this case the identifiers MUST belong to the same device. - NOTE2: as for this Commonalities release, we are enforcing that the networkAccessIdentifier is only part of the schema for future-proofing, and CAMARA does not currently allow its use. After the CAMARA meta-release work is concluded and the relevant issues are resolved, its use will need to be explicitly documented in the guidelines. + value: 1000000 + unit: Kbps + MaxDomainUpstreamRatePolicy: type: object properties: - phoneNumber: - $ref: "#/components/schemas/PhoneNumber" - networkAccessIdentifier: - $ref: "#/components/schemas/NetworkAccessIdentifier" - ipv4Address: - $ref: "#/components/schemas/DeviceIpv4Addr" - ipv6Address: - $ref: "#/components/schemas/DeviceIpv6Address" - # minProperties: 1 # NOTE: not used currently - - Device: - allOf: - - $ref: "#/components/schemas/BaseDevice" - - 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 - deviceStatus: - type: string - enum: - - connected - - disconnected - - unavailable - default: unavailable - description: The current status of the device - example: &device-status "connected" - required: - - id - example: &device - id: *device-id - deviceStatus: *device-status - name: *device-name - description: *device-description - hardwareAddress: *device-hardware-address - serviceSite: *service-site-id - networks: *device-network-intersection-list - maxAuxiliaryNetworks: *device-max-networks - - DeviceList: + value: + type: integer + description: Maximum upstream throughput across the domain. + unit: + type: string + enum: + - Kbps + - Mbps + - Gbps + description: Unit of measurement for upstream throughput. + required: + - value + - unit + description: Maximum upstream throughput policy across the Trust Domain. + example: + value: 500000 + unit: Kbps + EgressAllowedListPolicy: 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 - + type: string + description: FQDN or CIDR pattern + minItems: 1 + description: Restricts egress traffic to the specified destinations. + example: + - api.vendor.com + - updates.vendor.com + Policies: + type: object + description: A set of policies governing Trust Domain behavior. Omission of a policy indicates no constraint for that category. Policies are applied independently unless otherwise specified by the implementation. + properties: + maxDevices: + $ref: '#/components/schemas/MaxDevicesPolicy' + maxDomainDownstreamRate: + $ref: '#/components/schemas/MaxDomainDownstreamRatePolicy' + maxDomainUpstreamRate: + $ref: '#/components/schemas/MaxDomainUpstreamRatePolicy' + egressAllowedList: + $ref: '#/components/schemas/EgressAllowedListPolicy' + additionalProperties: false + example: + maxDevices: 10 + maxDomainDownstreamRate: + value: 500000 + unit: Kbps + maxDomainUpstreamRate: + value: 10000 + unit: Kbps + egressAllowedList: + - api.vendor.com + - updates.vendor.com WpaPersonalDetail: type: object + description: WPA Personal security mode configuration for Wi-Fi networks. properties: password: type: string + writeOnly: true + minLength: 8 maxLength: 255 + pattern: ^[\x20-\x7E]{8,63}$ description: The password for the WPA Personal Wi-Fi network - example: &wpa-personal-password "my-password" + example: my-password securityModeType: type: string enum: @@ -2011,78 +1440,123 @@ components: 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" + example: WPA3-Personal + additionalProperties: false required: - password - example: &wpa-personal - password: *wpa-personal-password - securityModeType: *wpa-personal-security-mode-type - + example: + password: my-password + securityModeType: WPA3-Personal + WiFiWpaPersonalAccessDetail: + type: object + description: Complete access details for Wi-Fi networks using WPA Personal security mode. + properties: + accessType: + type: string + description: The type of network access. + enum: + - Wi-Fi:WPA_PERSONAL + example: Wi-Fi:WPA_PERSONAL + ssid: + type: string + minLength: 2 + maxLength: 32 + pattern: ^(?! )[\x20-\x7E]{2,32}(?- - 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: + - $ref: '#/components/schemas/TrustDomainUpdate' + description: Represents the creation of a new trust domain within the network access management system. + required: + - name + - enabled + - accessDetails + - serviceId + properties: + serviceId: + $ref: '#/components/schemas/ServiceId' + ResourceAudit: + type: object + properties: + createdAt: + allOf: + - $ref: '#/components/schemas/DateTime' + - description: | + The creation date and time of the trust domain. 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). + - readOnly: true + createdBy: + allOf: + - $ref: '#/components/schemas/UUID' + description: | + The ID of the user or system that created this resource. + example: 550e8400-e29b-41d4-a716-446655440000 + readOnly: true + modifiedAt: + allOf: + - $ref: '#/components/schemas/DateTime' + - description: | + The last update date and time of the trust domain. 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). + - readOnly: true + modifiedBy: + allOf: + - $ref: '#/components/schemas/UUID' + description: | + The ID of the user or system that modified this resource. + example: 660e8400-e29b-41d4-a716-446655440000 + readOnly: true + description: A generic schema for resources with unique identifiers and audit fields. + TrustDomain: allOf: - - $ref: "#/components/schemas/NetworkUpdate" - - properties: + - $ref: '#/components/schemas/ResourceIdentifier' + - $ref: '#/components/schemas/TrustDomainCreate' + - $ref: '#/components/schemas/ResourceAudit' + - type: object + 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 + readOnly: true createdAt: - allOf: - - $ref: "#/components/schemas/DateTime" - - description: | - The creation date and time of the network. It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) - and must have time zone. Recommended format is yyyy-MM-dd'T'HH:mm:ss.SSSZ (i.e. which allows - 2023-07-03T14:27:08.312+02:00 or 2023-07-03T12:27:08.312Z). + readOnly: true createdBy: - type: string - maxLength: 100 - description: The user who created the network - example: &network-created-by "user-1" + readOnly: true modifiedAt: - allOf: - - $ref: "#/components/schemas/DateTime" - - description: | - The last update date and time of the network. It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) - and must have time zone. Recommended format is yyyy-MM-dd'T'HH:mm:ss.SSSZ (i.e. which allows - 2023-07-03T14:27:08.312+02:00 or 2023-07-03T12:27:08.312Z). + readOnly: true modifiedBy: - type: string - maxLength: 100 - description: The user who last updated the network - example: &network-modified-by "user-2" - version: - $ref: "#/components/schemas/NetworkVersion" - required: - - id - - accessDetail - example: &network - id: *network-id - description: *network-description - accessDetail: *wifi-access-detail - expiration: *date-time - devices: *network-device-intersection-list - createdAt: *date-time - createdBy: *network-created-by - modifiedAt: *date-time - modifiedBy: *network-modified-by - version: *network-version - - NetworkList: - type: array - items: - $ref: "#/components/schemas/Network" - example: &network-list - - *network - - id: *network-id2 - description: &network-description2 "my second network" - accessDetail: &network-access-detail2 - accessType: "Wi-Fi" - ssid: "my-second-ssid" - securityMode: - password: "my-other-password" - securityModeType: "WPA2-Personal" - expiration: *date-time - devices: &network-device-intersection-list2 - - device: *device-id2 - role: &network-role2 "auxiliary" - createdAt: *date-time - createdBy: &network-created-by2 "user-3" - modifiedAt: *date-time - modifiedBy: &network-modified-by2 "user-4" - version: &network-version2 "0000FFFF" - - DeviceNetworkReplacement: + readOnly: true + description: Represents a trust domain within the network access management system. + PhoneNumber: + description: A public identifier addressing a telephone subscription. In mobile networks it corresponds to the MSISDN (Mobile Station International Subscriber Directory Number). In order to be globally unique it has to be formatted in international format, according to E.164 standard, prefixed with '+'. + type: string + pattern: ^\+[1-9][0-9]{4,14}$ + example: '+123456789' + NetworkAccessIdentifier: + description: A public identifier addressing a subscription in a mobile network. In 3GPP terminology, it corresponds to the GPSI formatted with the External Identifier ({Local Identifier}@{Domain Identifier}). Unlike the telephone number, the network access identifier is not subjected to portability ruling in force, and is individually managed by each operator. + type: string + example: 123456789@example.com + SingleIpv4Addr: + description: A single IPv4 address with no subnet mask + type: string + format: ipv4 + example: 84.125.93.10 + Port: + description: TCP or UDP port number + type: integer + minimum: 0 + maximum: 65535 + DeviceIpv4Addr: 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" + The device should be identified by either the public (observed) IP address and port as seen by the application server, or the private (local) and any public (observed) IP addresses in use by the device (this information can be obtained by various means, for example from some DNS servers). - DeviceNetworkReplacementList: - type: array - items: - $ref: "#/components/schemas/DeviceNetworkReplacement" - example: &device-network-replacement-list - - *device-network-replacement + If the allocated and observed IP addresses are the same (i.e. NAT is not in use) then the same address should be specified for both publicAddress and privateAddress. - 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 + If NAT64 is in use, the device should be identified by its publicAddress and publicPort, or separately by its allocated IPv6 address (field ipv6Address of the Device object) - NetworkReplacement: - type: object + In all cases, publicAddress must be specified, along with at least one of either privateAddress or publicPort, dependent upon which is known. In general, mobile devices cannot be identified by their public IPv4 address alone. + properties: + publicAddress: + $ref: '#/components/schemas/SingleIpv4Addr' + privateAddress: + $ref: '#/components/schemas/SingleIpv4Addr' + publicPort: + $ref: '#/components/schemas/Port' + anyOf: + - required: + - publicAddress + - privateAddress + - required: + - publicAddress + - publicPort + example: + publicAddress: 84.125.93.10 + publicPort: 59765 + DeviceIpv6Address: + description: | + The device should be identified by the observed IPv6 address, or by any single IPv6 address from within the subnet allocated to the device (e.g. adding ::0 to the /64 prefix). + type: string + format: ipv6 + example: 2001:db8:85a3:8d3:1319:8a2e:370:7344 + Device: description: | - A network replacement operation. + End-user equipment able to connect to a mobile network. Examples of devices include smartphones or IoT sensors/actuators. + The developer can choose to provide the below specified device identifiers: + * `ipv4Address` + * `ipv6Address` + * `phoneNumber` + * `networkAccessIdentifier` + NOTE1: the network operator might support only a subset of these options. The API invoker can provide multiple identifiers to be compatible across different network operators. In this case the identifiers MUST belong to the same device. + NOTE2: as for this Commonalities release, we are enforcing that the networkAccessIdentifier is only part of the schema for future-proofing, and CAMARA does not currently allow its use. After the CAMARA meta-release work is concluded and the relevant issues are resolved, its use will need to be explicitly documented in the guidelines. + type: object 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: + phoneNumber: + $ref: '#/components/schemas/PhoneNumber' + networkAccessIdentifier: + $ref: '#/components/schemas/NetworkAccessIdentifier' + ipv4Address: + $ref: '#/components/schemas/DeviceIpv4Addr' + ipv6Address: + $ref: '#/components/schemas/DeviceIpv6Address' + minProperties: 1 + NetworkAccessDevice: + description: | + Represents a network access device managed within the network access management system. + This schema represents operator-supplied network access equipment (e.g., gateways, mesh Wi-Fi systems). + It extends the Commonalities Device model but MUST NOT be confused with end-user devices. + The identifiers and addressing fields reflect the operator-managed equipment, not client equipment. + allOf: + - $ref: '#/components/schemas/ResourceIdentifier' + - $ref: '#/components/schemas/Device' + - type: object + properties: + id: + readOnly: true + name: + type: string + minLength: 1 + maxLength: 100 + description: The name of the device + example: Gateway-1 + description: + type: string + minLength: 0 + maxLength: 255 + description: A description of the device + example: A Wi-Fi gateway device + hardwareAddress: + description: The hardware address of the device + oneOf: + - type: object + properties: + hardwareAddressType: + type: string + enum: + - EUI-48 + example: EUI-48 + value: + type: string + pattern: ^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$ + example: 12:34:56:78:9A:BC + required: + - hardwareAddressType + - value + discriminator: + propertyName: hardwareAddressType + example: + hardwareAddressType: EUI-48 + value: 12:34:56:78:9A:BC + serviceSite: + $ref: '#/components/schemas/ServiceSite' + deviceStatus: + type: string + enum: + - connected + - disconnected + - unavailable + default: unavailable + description: The current status of the device + example: connected + required: + - id + example: + id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 + deviceStatus: connected + name: Gateway-1 + description: A Wi-Fi gateway device + hardwareAddress: + hardwareAddressType: EUI-48 + value: 12:34:56:78:9A:BC + serviceSite: + id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 + name: Primary Residence + description: 123 Main Street + location: + id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 + addressLine1: 123 Main St + addressLine2: Suite 456 + streetNr: '123' + streetNrSuffix: A + streetNrLast: '125' + streetNrLastSuffix: B + streetName: Main + subUnitType: Apartment + subUnitNr: A12 + levelType: Floor + levelNr: '3' + buildingName: Sunset Towers + privateStreetName: Private Rd + locality: Example Locality + city: Example State + stateOrProvince: EX + country: United States + postCode: '12345' + postCodeExtension: '6789' + NetworkAccessDeviceList: type: array + description: A list of network access devices. 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 - + $ref: '#/components/schemas/NetworkAccessDevice' + example: + - id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 + deviceStatus: connected + name: Gateway-1 + description: A Wi-Fi gateway device + hardwareAddress: + hardwareAddressType: EUI-48 + value: 12:34:56:78:9A:BC + serviceSite: + id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 + name: Primary Residence + description: 123 Main Street + location: + id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 + addressLine1: 123 Main St + addressLine2: Suite 456 + streetNr: '123' + streetNrSuffix: A + streetNrLast: '125' + streetNrLastSuffix: B + streetName: Main + subUnitType: Apartment + subUnitNr: A12 + levelType: Floor + levelNr: '3' + buildingName: Sunset Towers + privateStreetName: Private Rd + locality: Example Locality + city: Example State + stateOrProvince: EX + country: United States + postCode: '12345' + postCodeExtension: '6789' + - id: 123e4567-e89b-12d3-a456-426614174000 + deviceStatus: disconnected + name: Gateway-2 + description: Another Wi-Fi gateway device + hardwareAddress: + hardwareAddressType: EUI-48 + value: AB:CD:EF:12:34:56 + serviceSite: + id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 + name: Primary Residence + description: 123 Main Street + location: + id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 + addressLine1: 123 Main St + addressLine2: Suite 456 + streetNr: '123' + streetNrSuffix: A + streetNrLast: '125' + streetNrLastSuffix: B + streetName: Main + subUnitType: Apartment + subUnitNr: A12 + levelType: Floor + levelNr: '3' + buildingName: Sunset Towers + privateStreetName: Private Rd + locality: Example Locality + city: Example State + stateOrProvince: EX + country: United States + postCode: '12345' + postCodeExtension: '6789' RebootRequestUpdate: type: object + description: Represents updatable fields for a reboot request, including optional message and scheduling information. properties: message: type: string maxLength: 255 description: A message related to the reboot request - example: &reboot-message "reboot to correct performance" + example: reboot to correct performance atTime: allOf: - - $ref: "#/components/schemas/DateTime" + - $ref: '#/components/schemas/DateTime' - description: | The date and time to reboot the device. Do not include 'atTime' to request immediate reboot. It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone. Recommended format is yyyy-MM-dd'T'HH:mm:ss.SSSZ (i.e. which allows 2023-07-03T14:27:08.312+02:00 or 2023-07-03T12:27:08.312Z). - example: &reboot-request-update - message: *reboot-message - atTime: *date-time - RebootRequestCreate: + description: Represents the creation of a reboot request, including target devices and optional scheduling. If devices is omitted, the provider MAY infer a default device. Inference rules vary by implementation. If inference is unsupported or ambiguous, creation MUST fail. allOf: - - $ref: "#/components/schemas/RebootRequestUpdate" + - $ref: '#/components/schemas/RebootRequestUpdate' - properties: devices: type: array items: - $ref: "#/components/schemas/DeviceId" - description: >- - List of devices to reboot. When undefined, the reboot targets the 'default' device (simple use case that - wouldn't use locations or devices). Throws an error when creating if there is no 'default' device. - example: *device-id-list - example: &reboot-create - message: *reboot-message - atTime: *date-time - devices: *device-id-list - - RebootRequest: - allOf: - - $ref: "#/components/schemas/RebootRequestCreate" - - properties: - id: - $ref: "#/components/schemas/RebootId" - createdAt: - allOf: - - $ref: "#/components/schemas/DateTime" - - description: | - The creation date and time of the reboot request. It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) - and must have time zone. Recommended format is yyyy-MM-dd'T'HH:mm:ss.SSSZ (i.e. which allows - 2023-07-03T14:27:08.312+02:00 or 2023-07-03T12:27:08.312Z). - createdBy: - type: string - maxLength: 100 - description: The user who created the reboot request - example: &reboot-created-by "user-1" - modifiedAt: - allOf: - - $ref: "#/components/schemas/DateTime" - - description: | - The last update date and time of the reboot request. It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) - and must have time zone. Recommended format is yyyy-MM-dd'T'HH:mm:ss.SSSZ (i.e. which allows - 2023-07-03T14:27:08.312+02:00 or 2023-07-03T12:27:08.312Z). - modifiedBy: - type: string - maxLength: 100 - description: The user who last updated the reboot request - example: &reboot-modified-by "user-2" - required: - - id - example: &reboot-request - id: *reboot-id - message: *reboot-message - atTime: *date-time - devices: *device-id-list - createdAt: *date-time - createdBy: *reboot-created-by - modifiedAt: *date-time - modifiedBy: *reboot-modified-by - - RebootRequestList: - type: array - items: - $ref: "#/components/schemas/RebootRequest" - example: &reboot-request-list - - *reboot-request - - id: &reboot-id2 "reboot-2" - message: &reboot-message2 "my second reboot request" - atTime: *date-time - devices: &reboot-devices2 - - "device-3" - - "device-4" - createdAt: *date-time - createdBy: &reboot-created-by2 "user-3" - modifiedAt: *date-time - modifiedBy: &reboot-modified-by2 "user-4" - - examples: - BaseServiceSite: - summary: Base Service Site - description: | - Output with the following scope(s): - - `network-access-management:service-sites:read` - value: &base-service-site - id: *service-site-id - - ServiceSiteWithLocation: - summary: Service Site with Location - description: | - Output with the following scope(s): - - `network-access-management:service-sites.location:read` - value: &service-site-with-location - id: *service-site-id - name: *service-site-name - description: *service-site-description - location: *service-site-location - - ServiceSiteWithDevices: - summary: Service Site with Devices - description: | - Output with the following scope(s): - - **all of** - - `network-access-management:service-sites:read` - - **one of** - - `network-access-management:devices:read` - - `network-access-management:devices:write` - - `network-access-management:devices.hardware-address:read` - value: &service-site-with-devices - id: *service-site-id - devices: *device-id-list - - ServiceSiteWithLocationAndDevices: - summary: Service Site with Location and Devices - description: | - Output with the following scope(s): - - **all of** - - `network-access-management:service-sites.location:read` - - **one of** - - `network-access-management:devices:read` - - `network-access-management:devices:write` - - `network-access-management:devices.hardware-address:read` - value: *service-site - - BaseServiceSiteList: - summary: Base Service Site List - description: | - Output with the following scope(s): - - **all of** - - `network-access-management:service-sites:read` - value: - - *base-service-site - - id: *service-site-id2 - - ServiceSiteListWithLocation: - summary: Service Site List with Location - description: | - Output with the following scope(s): - - **all of** - - `network-access-management:service-sites.location:read` - value: - - *service-site-with-location - - id: *service-site-id2 - name: *service-site-name2 - description: *service-site-description2 - location: *service-site-location2 - - ServiceSiteListWithDevices: - summary: Service Site List with Devices - description: | - Output with the following scope(s): - - **all of** - - `network-access-management:service-sites:read` - - **one of** - - `network-access-management:devices:read` - - `network-access-management:devices:write` - - `network-access-management:devices.hardware-address:read` - value: - - *service-site-with-devices - - id: *service-site-id2 - devices: *service-site-devices2 - - ServiceSiteListWithLocationAndDevices: - summary: Service Site List with Location and Devices - description: | - Output with the following scope(s): - - **all of** - - `network-access-management:service-sites.location:read` - - **one of** - - `network-access-management:devices:read` - - `network-access-management:devices:write` - - `network-access-management:devices.hardware-address:read` - value: *service-site-list - - BaseDevice: - summary: Base Device - description: | - Output with the following scope(s): - - **one of** - - `network-access-management:devices:read` - - `network-access-management:devices:write` - value: &base-device - id: *device-id - name: *device-name - description: *device-description - - DeviceWithHardwareAddress: - summary: Device with Hardware Address - description: | - Output with the following scope(s): - - **all of** - - `network-access-management:devices.hardware-address:read` - value: &device-with-hardware-address - id: *device-id - deviceStatus: *device-status - name: *device-name - description: *device-description - hardwareAddress: *device-hardware-address - - DeviceWithServiceSite: - summary: Device with Service Site - description: | - Output with the following scope(s): - - **all of** - - **one of** - - `network-access-management:devices:read` - - `network-access-management:devices:write` - - **one of** - - `network-access-management:service-sites:read` - - `network-access-management:service-sites.location:read` - value: &device-with-service-site - id: *device-id - deviceStatus: *device-status - name: *device-name - description: *device-description - serviceSite: *service-site-id - - DeviceWithNetworks: - summary: Device with Networks - description: | - Output with the following scope(s): - - **all of** - - **one of** - - `network-access-management:devices:read` - - `network-access-management:devices:write` - - **one of** - - `network-access-management:isolated-networks:wifi:read` - - `network-access-management:isolated-networks:wifi:write` - - `network-access-management:isolated-networks:wifi.primary:read` - - `network-access-management:isolated-networks:wifi.primary:write` - - `network-access-management:isolated-networks:wifi.auxiliary:read` - - `network-access-management:isolated-networks:wifi.auxiliary:write` - value: &device-with-networks - id: *device-id - deviceStatus: *device-status - name: *device-name - description: *device-description - networks: *device-network-intersection-list - maxAuxiliaryNetworks: *device-max-networks - - DeviceWithHardwareAddressAndServiceSite: - summary: Device with Hardware Address and Service Site - description: | - Output with the following scope(s): - - **all of** - - `network-access-management:devices.hardware-address:read` - - **one of** - - `network-access-management:service-sites:read` - - `network-access-management:service-sites.location:read` - value: &device-with-hardware-address-and-service-site - id: *device-id - deviceStatus: *device-status - name: *device-name - description: *device-description - hardwareAddress: *device-hardware-address - serviceSite: *service-site-id - - DeviceWithHardwareAddressAndNetworks: - summary: Device with Hardware Address and Networks - description: | - Output with the following scope(s): - - **all of** - - `network-access-management:devices.hardware-address:read` - - **one of** - - `network-access-management:isolated-networks:wifi:read` - - `network-access-management:isolated-networks:wifi:write` - - `network-access-management:isolated-networks:wifi.primary:read` - - `network-access-management:isolated-networks:wifi.primary:write` - - `network-access-management:isolated-networks:wifi.auxiliary:read` - - `network-access-management:isolated-networks:wifi.auxiliary:write` - value: &device-with-hardware-address-and-networks - id: *device-id - deviceStatus: *device-status - name: *device-name - description: *device-description - hardwareAddress: *device-hardware-address - networks: *device-network-intersection-list - maxAuxiliaryNetworks: *device-max-networks - - DeviceWithServiceSiteAndNetworks: - summary: Device with Service Site and Networks - description: | - Output with the following scope(s): - - **all of** - - **one of** - - `network-access-management:devices:read` - - `network-access-management:devices:write` - - **one of** - - `network-access-management:service-sites:read` - - `network-access-management:service-sites.location:read` - - **one of** - - `network-access-management:isolated-networks:wifi:read` - - `network-access-management:isolated-networks:wifi:write` - - `network-access-management:isolated-networks:wifi.primary:read` - - `network-access-management:isolated-networks:wifi.primary:write` - - `network-access-management:isolated-networks:wifi.auxiliary:read` - - `network-access-management:isolated-networks:wifi.auxiliary:write` - value: &device-with-service-site-and-networks - id: *device-id - deviceStatus: *device-status - name: *device-name - description: *device-description - serviceSite: *service-site-id - networks: *device-network-intersection-list - maxAuxiliaryNetworks: *device-max-networks - - DeviceWithHardwareAddressAndServiceSiteAndNetworks: - summary: Device with Hardware Address, Service Site, and Networks - description: | - Output with the following scope(s): - - **all of** - - `network-access-management:devices.hardware-address:read` - - **one of** - - `network-access-management:service-sites:read` - - `network-access-management:service-sites.location:read` - - **one of** - - `network-access-management:isolated-networks:wifi:read` - - `network-access-management:isolated-networks:wifi:write` - - `network-access-management:isolated-networks:wifi.primary:read` - - `network-access-management:isolated-networks:wifi.primary:write` - - `network-access-management:isolated-networks:wifi.auxiliary:read` - - `network-access-management:isolated-networks:wifi.auxiliary:write` - value: *device - - BaseDeviceList: - summary: Base Device List - description: | - Output with the following scope(s): - - **one of** - - `network-access-management:devices:read` - - `network-access-management:devices:write` - value: - - *base-device - - id: *device-id2 - deviceStatus: *device-status - name: *device-name2 - description: *device-description2 - - DeviceListWithHardwareAddress: - summary: Device List with Hardware Address - description: | - Output with the following scope(s): - - **all of** - - `network-access-management:devices.hardware-address:read` - value: - - *device-with-hardware-address - - id: *device-id2 - deviceStatus: *device-status - name: *device-name2 - description: *device-description2 - hardwareAddress: *device-hardware-address2 - - DeviceListWithServiceSite: - summary: Device List with Service Site - description: | - Output with the following scope(s): - - **all of** - - **one of** - - `network-access-management:devices:read` - - `network-access-management:devices:write` - - **one of** - - `network-access-management:service-sites:read` - - `network-access-management:service-sites.location:read` - value: - - *device-with-service-site - - id: *device-id2 - deviceStatus: *device-status - name: *device-name2 - description: *device-description2 - serviceSite: *service-site-id2 - - DeviceListWithNetworks: - summary: Device List with Networks - description: | - Output with the following scope(s): - - **all of** - - **one of** - - `network-access-management:devices:read` - - `network-access-management:devices:write` - - **one of** - - `network-access-management:isolated-networks:wifi:read` - - `network-access-management:isolated-networks:wifi:write` - - `network-access-management:isolated-networks:wifi.primary:read` - - `network-access-management:isolated-networks:wifi.primary:write` - - `network-access-management:isolated-networks:wifi.auxiliary:read` - - `network-access-management:isolated-networks:wifi.auxiliary:write` - value: - - *device-with-networks - - id: *device-id2 - deviceStatus: *device-status - name: *device-name2 - description: *device-description2 - networks: *device-network-intersection-list - maxAuxiliaryNetworks: *device-max-networks2 - - DeviceListWithHardwareAddressAndServiceSite: - summary: Device List with Hardware Address and Service Site - description: | - Output with the following scope(s): - - **all of** - - `network-access-management:devices.hardware-address:read` - - **one of** - - `network-access-management:service-sites:read` - - `network-access-management:service-sites.location:read` - value: - - *device-with-hardware-address-and-service-site - - id: *device-id2 - deviceStatus: *device-status - name: *device-name2 - description: *device-description2 - hardwareAddress: *device-hardware-address2 - serviceSite: *service-site-id2 - - DeviceListWithHardwareAddressAndNetworks: - summary: Device List with Hardware Address and Networks - description: | - Output with the following scope(s): - - **all of** - - `network-access-management:devices.hardware-address:read` - - **one of** - - `network-access-management:isolated-networks:wifi:read` - - `network-access-management:isolated-networks:wifi:write` - - `network-access-management:isolated-networks:wifi.primary:read` - - `network-access-management:isolated-networks:wifi.primary:write` - - `network-access-management:isolated-networks:wifi.auxiliary:read` - - `network-access-management:isolated-networks:wifi.auxiliary:write` - value: - - *device-with-hardware-address-and-networks - - id: *device-id2 - deviceStatus: *device-status - name: *device-name2 - description: *device-description2 - hardwareAddress: *device-hardware-address2 - networks: *device-network-intersection-list - maxAuxiliaryNetworks: *device-max-networks2 - - DeviceListWithServiceSiteAndNetworks: - summary: Device List with Service Site and Networks - description: | - Output with the following scope(s): - - **all of** - - **one of** - - `network-access-management:devices:read` - - `network-access-management:devices:write` - - **one of** - - `network-access-management:service-sites:read` - - `network-access-management:service-sites.location:read` - - **one of** - - `network-access-management:isolated-networks:wifi:read` - - `network-access-management:isolated-networks:wifi:write` - - `network-access-management:isolated-networks:wifi.primary:read` - - `network-access-management:isolated-networks:wifi.primary:write` - - `network-access-management:isolated-networks:wifi.auxiliary:read` - - `network-access-management:isolated-networks:wifi.auxiliary:write` - value: - - *device-with-service-site-and-networks - - id: *device-id2 - deviceStatus: *device-status - name: *device-name2 - description: *device-description2 - serviceSite: *service-site-id2 - networks: *device-network-intersection-list - maxAuxiliaryNetworks: *device-max-networks2 - - DeviceListWithHardwareAddressAndServiceSiteAndNetworks: - summary: Device List with Hardware Address, Service Site, and Networks - description: | - Output with the following scope(s): - - **all of** - - `network-access-management:devices.hardware-address:read` - - **one of** - - `network-access-management:service-sites:read` - - `network-access-management:service-sites.location:read` - - **one of** - - `network-access-management:isolated-networks:wifi:read` - - `network-access-management:isolated-networks:wifi:write` - - `network-access-management:isolated-networks:wifi.primary:read` - - `network-access-management:isolated-networks:wifi.primary:write` - - `network-access-management:isolated-networks:wifi.auxiliary:read` - - `network-access-management:isolated-networks:wifi.auxiliary:write` - value: *device-list - - BaseNetwork: - summary: Network Configuration with Default Device - description: | - Output with the following scope(s): - - **one of** - - `network-access-management:isolated-networks:wifi:read` - - `network-access-management:isolated-networks:wifi:write` - - `network-access-management:isolated-networks:wifi.primary:read` - - `network-access-management:isolated-networks:wifi.primary:write` - - `network-access-management:isolated-networks:wifi.auxiliary:read` - - `network-access-management:isolated-networks:wifi.auxiliary:write` - value: &base-network - id: *network-id - description: *network-description - accessDetail: *wifi-access-detail - expiration: *date-time - createdAt: *date-time - createdBy: *network-created-by - modifiedAt: *date-time - modifiedBy: *network-modified-by - version: *network-version - - NetworkWithDevices: - summary: Network Configuration - description: | - Output with the following scope(s): - - **all of** - - **one of** - - `network-access-management:isolated-networks:wifi:read` - - `network-access-management:isolated-networks:wifi:write` - - `network-access-management:isolated-networks:wifi.primary:read` - - `network-access-management:isolated-networks:wifi.primary:write` - - `network-access-management:isolated-networks:wifi.auxiliary:read` - - `network-access-management:isolated-networks:wifi.auxiliary:write` - - **one of** - - `network-access-management:devices:read` - - `network-access-management:devices:write` - - `network-access-management:devices.hardware-address:read` - value: *network - - NetworkUpdate: - summary: Network Update - description: | - Post with the following scope(s): - - **one of** - - `network-access-management:isolated-networks:wifi:write` - - `network-access-management:isolated-networks:wifi.primary:write` - - `network-access-management:isolated-networks:wifi.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:wifi:write` - - `network-access-management:isolated-networks:wifi.primary:write` - - `network-access-management:isolated-networks:wifi.auxiliary:write` - value: - description: *network-description - accessDetail: *wifi-access-detail - expiration: *date-time - - NetworkCreateWithDevices: - summary: Create Network on Devices - description: | - Post with the following scope(s): - - **all of** - - `network-access-management:devices:write` - - **one of** - - `network-access-management:isolated-networks:wifi:write` - - `network-access-management:isolated-networks:wifi.primary:write` - - `network-access-management:isolated-networks:wifi.auxiliary:write` - value: *network-create - - BaseNetworkList: - summary: Network List with Default Device - description: | - Output with the following scope(s): - - **one of** - - `network-access-management:isolated-networks:wifi:read` - - `network-access-management:isolated-networks:wifi:write` - - `network-access-management:isolated-networks:wifi.primary:read` - - `network-access-management:isolated-networks:wifi.primary:write` - - `network-access-management:isolated-networks:wifi.auxiliary:read` - - `network-access-management:isolated-networks:wifi.auxiliary:write` - value: - - *base-network - - id: *network-id2 - description: *network-description2 - accessDetail: *network-access-detail2 - expiration: *date-time - createdAt: *date-time - createdBy: *date-time - modifiedAt: *date-time - modifiedBy: *network-modified-by2 - version: *network-version2 - - NetworkListWithDevices: - summary: Network List with Devices - description: | - Output with the following scope(s): - - **all of** - - **one of** - - `network-access-management:isolated-networks:wifi:read` - - `network-access-management:isolated-networks:wifi:write` - - `network-access-management:isolated-networks:wifi.primary:read` - - `network-access-management:isolated-networks:wifi.primary:write` - - `network-access-management:isolated-networks:wifi.auxiliary:read` - - `network-access-management:isolated-networks:wifi.auxiliary:write` - - **one of** - - `network-access-management:devices:read` - - `network-access-management:devices:write` - - `network-access-management:devices.hardware-address:read` - value: *network-list - - BaseRebootRequest: - summary: Reboot Request with Default Device - description: | - Output with the following scope(s): - - **one of** - - `network-access-management:reboot-requests:read` - - `network-access-management:reboot-requests:write` - value: &base-reboot-request - id: *reboot-id - message: *reboot-message - atTime: *date-time - createdAt: *date-time - createdBy: *reboot-created-by - modifiedAt: *date-time - modifiedBy: *reboot-modified-by - - RebootRequestWithDevices: - summary: Reboot Request - description: | - Output with the following scope(s): - - **all of** - - **one of** - - `network-access-management:reboot-requests:read` - - `network-access-management:reboot-requests:write` - - **one of** - - `network-access-management:devices:read` - - `network-access-management:devices:write` - - `network-access-management:devices.hardware-address:read` - value: *reboot-request - - RebootRequestUpdate: - summary: Reboot Request Update - description: | - Post with the following scope(s): - - **one of** - - `network-access-management:reboot-requests:write` - value: *reboot-request-update - - BaseRebootRequestCreate: - summary: Create Reboot Request for Default Device - description: | - Post with the following scope(s): - - **all of** - - `network-access-management:reboot-requests:write` - value: &reboot-request-update - message: *reboot-message - atTime: *date-time - - RebootRequestCreateWithDevices: - summary: Create Reboot Request for Devices - description: | - Post with the following scope(s): - - **all of** - - `network-access-management:devices:write` - - `network-access-management:reboot-requests:write` - value: *reboot-create - - BaseRebootRequestList: - summary: Reboot Request List with Default Device - description: | - Output with the following scope(s): - - **one of** - - `network-access-management:reboot-requests:read` - - `network-access-management:reboot-requests:write` - value: - - *base-reboot-request - - id: *reboot-id2 - message: *reboot-message2 - atTime: *date-time - createdAt: *date-time - createdBy: *reboot-created-by2 - modifiedAt: *date-time - modifiedBy: *reboot-modified-by2 - - RebootRequestListWithDevices: - summary: Reboot Request List - description: | - Output with the following scope(s): - - **all of** - - **one of** - - `network-access-management:reboot-requests:read` - - `network-access-management:reboot-requests:write` - - **one of** - - `network-access-management:devices:read` - - `network-access-management:devices:write` - - `network-access-management:devices.hardware-address:read` - value: *reboot-request-list - - responses: - Generic400: - description: Bad Request - headers: - x-correlator: - $ref: "#/components/headers/x-correlator" - content: - application/json: - schema: - allOf: - - $ref: "#/components/schemas/ErrorInfo" - - type: object - properties: - status: - enum: - - 400 - code: - enum: - - INVALID_ARGUMENT - - OUT_OF_RANGE - examples: - GENERIC_400_INVALID_ARGUMENT: - description: Invalid Argument. Generic Syntax Exception - value: - status: 400 - code: INVALID_ARGUMENT - message: Client specified an invalid argument, request body or query param. - GENERIC_400_OUT_OF_RANGE: - description: Out of Range. Specific Syntax Exception used when a given field has a pre-defined range or a invalid filter criteria combination is requested - value: - status: 400 - code: OUT_OF_RANGE - message: Client specified an invalid range. - + $ref: '#/components/schemas/UUID' + 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: + - 934ee3f4-1234-5678-9abc-abcdef123456 + - 454ee3f4-1234-5678-9abc-abcdef123456 + RebootRequest: + allOf: + - $ref: '#/components/schemas/ResourceIdentifier' + - $ref: '#/components/schemas/RebootRequestCreate' + - $ref: '#/components/schemas/ResourceAudit' + - type: object + properties: + id: + readOnly: true + createdAt: + readOnly: true + createdBy: + readOnly: true + modifiedAt: + readOnly: true + modifiedBy: + readOnly: true + required: + - devices + description: Represents a reboot request for one or more network access devices. + headers: + x-correlator: + description: Correlation id for the different services + schema: + $ref: '#/components/schemas/XCorrelator' + responses: Generic401: description: Unauthorized headers: x-correlator: - $ref: "#/components/headers/x-correlator" + $ref: '#/components/headers/x-correlator' content: application/json: schema: allOf: - - $ref: "#/components/schemas/ErrorInfo" + - $ref: '#/components/schemas/ErrorInfo' - type: object properties: status: @@ -3169,22 +2082,21 @@ components: - UNAUTHENTICATED examples: GENERIC_401_UNAUTHENTICATED: - description: Request cannot be authenticated + description: Request cannot be authenticated and a new authentication is required value: status: 401 code: UNAUTHENTICATED - message: Request not authenticated due to missing, invalid, or expired credentials. - + message: Request not authenticated due to missing, invalid, or expired credentials. A new authentication is required. Generic403: description: Forbidden headers: x-correlator: - $ref: "#/components/headers/x-correlator" + $ref: '#/components/headers/x-correlator' content: application/json: schema: allOf: - - $ref: "#/components/schemas/ErrorInfo" + - $ref: '#/components/schemas/ErrorInfo' - type: object properties: status: @@ -3206,18 +2118,42 @@ components: value: status: 403 code: INVALID_TOKEN_CONTEXT - message: "{{field}} is not consistent with access token." - + message: '{{field}} is not consistent with access token.' + Generic500: + description: Internal Server Error + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/ErrorInfo' + - type: object + properties: + status: + enum: + - 500 + code: + enum: + - INTERNAL + examples: + GENERIC_500_INTERNAL: + description: Problem in Server side. Regular Server Exception + value: + status: 500 + code: INTERNAL + message: Unknown server error. Typically a server bug. Generic404: description: Not found headers: x-correlator: - $ref: "#/components/headers/x-correlator" + $ref: '#/components/headers/x-correlator' content: application/json: schema: allOf: - - $ref: "#/components/schemas/ErrorInfo" + - $ref: '#/components/schemas/ErrorInfo' - type: object properties: status: @@ -3227,9 +2163,6 @@ components: enum: - NOT_FOUND - IDENTIFIER_NOT_FOUND - - SERVICE_SITE_NOT_FOUND - - DEVICE_NOT_FOUND - - NETWORK_NOT_FOUND examples: GENERIC_404_NOT_FOUND: description: Resource is not found @@ -3237,90 +2170,79 @@ components: status: 404 code: NOT_FOUND message: The specified resource is not found. - GENERIC_404_SERVICE_SITE_NOT_FOUND: - description: Service site identitier not found + GENERIC_404_IDENTIFIER_NOT_FOUND: + description: Some identifier cannot be matched to a device value: status: 404 - code: SERVICE_SITE_NOT_FOUND - message: | - Service site identifier(s) not found: {{ServiceSiteId, ...}}. - GENERIC_404_DEVICE_NOT_FOUND: - description: Device identifier(s) not found - value: - status: 404 - code: DEVICE_NOT_FOUND - message: | - Device identifier(s) not found: {{DeviceId, ...}}. - GENERIC_404_NETWORK_NOT_FOUND: - description: Network identitier(s) not found - value: - status: 404 - code: NETWORK_NOT_FOUND - message: | - Network identitifer(s) not found: {{NetworkId, ...}}. - - Generic405: - description: Method Not Allowed + code: IDENTIFIER_NOT_FOUND + message: Device identifier not found. + Generic503: + description: Service Unavailable headers: x-correlator: - $ref: "#/components/headers/x-correlator" + $ref: '#/components/headers/x-correlator' content: application/json: schema: allOf: - - $ref: "#/components/schemas/ErrorInfo" + - $ref: '#/components/schemas/ErrorInfo' - type: object properties: status: enum: - - 405 + - 503 code: enum: - - METHOD_NOT_ALLOWED + - UNAVAILABLE examples: - GENERIC_405_METHOD_NOT_ALLOWED: - description: Invalid HTTP verb used with a given endpoint + GENERIC_503_UNAVAILABLE: + description: Service is not available. Temporary situation usually related to maintenance process in the server side value: - status: 405 - code: METHOD_NOT_ALLOWED - message: The requested method is not allowed/supported on the target resource. - - Generic406: - description: Not Acceptable + status: 503 + code: UNAVAILABLE + message: Service Unavailable. + Generic400: + description: Bad Request headers: x-correlator: - $ref: "#/components/headers/x-correlator" + $ref: '#/components/headers/x-correlator' content: application/json: schema: allOf: - - $ref: "#/components/schemas/ErrorInfo" + - $ref: '#/components/schemas/ErrorInfo' - type: object properties: status: enum: - - 406 + - 400 code: enum: - - NOT_ACCEPTABLE + - INVALID_ARGUMENT + - OUT_OF_RANGE examples: - GENERIC_406_NOT_ACCEPTABLE: - description: API Server does not accept the media type (`Accept-*` header) indicated by API client + GENERIC_400_INVALID_ARGUMENT: + description: Invalid Argument. Generic Syntax Exception value: - status: 406 - code: NOT_ACCEPTABLE - message: The server cannot produce a response matching the content requested by the client through `Accept-*` headers. - + status: 400 + code: INVALID_ARGUMENT + message: Client specified an invalid argument, request body or query param. + GENERIC_400_OUT_OF_RANGE: + description: Out of Range. Specific Syntax Exception used when a given field has a pre-defined range or a invalid filter criteria combination is requested + value: + status: 400 + code: OUT_OF_RANGE + message: Client specified an invalid range. Generic409: description: Conflict headers: x-correlator: - $ref: "#/components/headers/x-correlator" + $ref: '#/components/headers/x-correlator' content: application/json: schema: allOf: - - $ref: "#/components/schemas/ErrorInfo" + - $ref: '#/components/schemas/ErrorInfo' - type: object properties: status: @@ -3331,7 +2253,6 @@ components: - ABORTED - ALREADY_EXISTS - CONFLICT - - NETWORK_NOT_REMOVABLE examples: GENERIC_409_ABORTED: description: Concurreny of processes of the same nature/scope @@ -3351,102 +2272,16 @@ components: status: 409 code: CONFLICT message: A specified resource duplicate entry found. - GENERIC_409_NETWORK_NOT_REMOVABLE: - description: The specified network cannot be removed - value: - status: 409 - code: NETWORK_NOT_REMOVABLE - message: | - The specified network cannot be removed: {{NetworkId}}: {{reason}} - - Generic410: - description: Gone - headers: - x-correlator: - $ref: "#/components/headers/x-correlator" - content: - application/json: - schema: - allOf: - - $ref: "#/components/schemas/ErrorInfo" - - type: object - properties: - status: - enum: - - 410 - code: - enum: - - GONE - examples: - GENERIC_410_GONE: - description: Use in notifications flow to allow API Consumer to indicate that its callback is no longer available - value: - status: 410 - code: GONE - message: Access to the target resource is no longer available. - - Generic412: - description: Failed precondition - headers: - x-correlator: - $ref: "#/components/headers/x-correlator" - content: - application/json: - schema: - allOf: - - $ref: "#/components/schemas/ErrorInfo" - - type: object - properties: - status: - enum: - - 412 - code: - enum: - - FAILED_PRECONDITION - examples: - GENERIC_412_FAILED_PRECONDITION: - description: Indication by the API Server that the request cannot be processed in current system state - value: - status: 412 - code: FAILED_PRECONDITION - message: Request cannot be executed in the current system state. - - Generic415: - description: Unsupported Media Type - headers: - x-correlator: - $ref: "#/components/headers/x-correlator" - content: - application/json: - schema: - allOf: - - $ref: "#/components/schemas/ErrorInfo" - - type: object - properties: - status: - enum: - - 415 - code: - enum: - - UNSUPPORTED_MEDIA_TYPE - examples: - GENERIC_415_UNSUPPORTED_MEDIA_TYPE: - description: Payload format of the request is in an unsupported format by the Server. Should not happen - value: - status: 415 - code: UNSUPPORTED_MEDIA_TYPE - message: The server refuses to accept the request because the payload format is in an unsupported format. - Generic422: description: Unprocessable Content headers: x-correlator: - $ref: "#/components/headers/x-correlator" + $ref: '#/components/headers/x-correlator' content: application/json: schema: allOf: - - $ref: "#/components/schemas/ErrorInfo" + - $ref: '#/components/schemas/ErrorInfo' - type: object properties: status: @@ -3483,166 +2318,165 @@ components: status: 422 code: UNNECESSARY_IDENTIFIER message: The device is already identified by the access token. + examples: + TrustDomainCreateWpa2Personal: + summary: Create a Trust Domain with WPA2-Personal Wi-Fi access. + value: + name: Primary WiFi Network + description: Request defines a Trust Domain with WPA2-Personal Wi-Fi access. The request specifies an SSID, implying the SSID is created on the network infrastructure. + enabled: true + accessDetails: + - accessType: Wi-Fi:WPA_PERSONAL + ssid: my-ssid + securityMode: + password: my-password + securityModeType: WPA2-Personal + serviceId: 123e4567-e89b-12d3-a456-426614174000 + TrustDomainCreateInferredSsid: + summary: Create a Trust Domain with inferred SSID Wi-Fi access. + value: + name: Inferred SSID Network + description: Request defines a Trust Domain with inferred SSID Wi-Fi access. The request omits the SSID, implying the Trust Domain is applied to an existing SSID on the network infrastructure. + enabled: true + accessDetails: + - accessType: Wi-Fi:WPA_PERSONAL + securityMode: + password: my-password + securityModeType: WPA2-Personal + serviceId: 123e4567-e89b-12d3-a456-426614174000 + TrustDomainCreateThreadStructured: + summary: Create a Trust Domain with Thread structured access details. + value: + name: Thread Structured Network + description: Request defines a Trust Domain with Thread structured access details. + enabled: true + accessDetails: + - accessType: Thread:STRUCTURED + channel: 13 + extendedPanId: d63e8e3e495ebbc3 + networkKey: dfd34f0f05cad978ec4e32b0413038ff + networkName: Spec-Thread-B3AF + panId: d63e + serviceId: 123e4567-e89b-12d3-a456-426614174000 + TrustDomainCreateEphemeral: + summary: Create a Trust Domain with ephemeral access details. + value: + name: Ephemeral Network + description: Request defines a Trust Domain with ephemeral access details. + enabled: true + accessDetails: + - accessType: Wi-Fi:WPA_PERSONAL + ssid: my-ssid + securityMode: + password: my-password + securityModeType: WPA3-Personal + expiration: '2024-12-31T23:59:59Z' + policies: + maxDevices: 10 + serviceId: 123e4567-e89b-12d3-a456-426614174000 + TrustDomainCreateQoSPolicies: + summary: Create a Trust Domain with QoS policies. + value: + name: QoS Policy Network + description: Request defines a Trust Domain with QoS policies. + enabled: true + accessDetails: + - accessType: Wi-Fi:WPA_PERSONAL + ssid: my-ssid + securityMode: + password: my-password + securityModeType: WPA3-Personal + policies: + maxDomainDownstreamRate: + value: 1000000 + unit: Kbps + maxDomainUpstreamRate: + value: 500000 + unit: Kbps + serviceId: 123e4567-e89b-12d3-a456-426614174000 + TrustDomainResponseBasic: + summary: Basic Trust Domain Response + description: Example of a created Trust Domain with minimal details. + value: + id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 + name: Basic Trust Domain + description: A basic trust domain example + enabled: true + accessDetails: + - accessType: Wi-Fi:WPA_PERSONAL + ssid: my-ssid + securityMode: + password: my-password + securityModeType: WPA2-Personal + serviceId: 123e4567-e89b-12d3-a456-426614174000 + createdAt: '2025-10-21T14:27:08.312Z' + createdBy: 550e8400-e29b-41d4-a716-446655440000 + modifiedAt: '2025-10-21T14:27:08.312Z' + modifiedBy: 660e8400-e29b-41d4-a716-446655440000 + TrustDomainResponseWiFiThread: + summary: Created Trust Domain (Wi-Fi + Thread) + description: Example of a created Trust Domain including Wi-Fi and Thread access details and populated policies. + value: + id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 + name: Primary WiFi Network + description: Primary home Wi-Fi Network for all devices + enabled: true + expiration: '2025-10-21T14:27:08.312Z' + policies: + egressAllowedList: + - api.vendor.com + - updates.vendor.com + accessDetails: + - accessType: Wi-Fi:WPA_PERSONAL + ssid: my-ssid + securityMode: + password: my-password + securityModeType: WPA3-Personal + - accessType: Thread:STRUCTURED + channel: 13 + extendedPanId: d63e8e3e495ebbc3 + networkKey: dfd34f0f05cad978ec4e32b0413038ff + networkName: Spec-Thread-B3AF + panId: d63e + serviceId: 123e4567-e89b-12d3-a456-426614174000 + createdAt: '2025-10-21T14:27:08.312Z' + createdBy: 550e8400-e29b-41d4-a716-446655440000 + modifiedAt: '2025-10-21T14:27:08.312Z' + modifiedBy: 770e8400-e29b-41d4-a716-446655440000 + RebootRequestCreateImmediateDefaultDevice: + summary: Example of a Reboot Request for immediate reboot + value: + message: reboot to correct performance + RebootRequestCreateScheduledMultipleDevices: + summary: Example of a Reboot Request for scheduled reboot of multiple devices + value: + message: Scheduled reboot for maintenance + atTime: '2023-07-03T12:27:08.312Z' + devices: + - 934ee3f4-1234-5678-9abc-abcdef123456 + - 454ee3f4-1234-5678-9abc-abcdef123456 + parameters: + trustDomainId: + name: trustDomainId + in: path + required: true + schema: + $ref: '#/components/schemas/UUID' + description: ID of the Trust Domain. If the Trust Domain exists but the caller lacks permission to access it, the API returns 403. + networkAccessDeviceId: + name: networkAccessDeviceId + in: path + description: | + The unique identifier of the Network Access Device. If the device exists but the caller lacks permission to access it, the API returns 403. - Generic429: - description: Too Many Requests - headers: - x-correlator: - $ref: "#/components/headers/x-correlator" - content: - application/json: - schema: - allOf: - - $ref: "#/components/schemas/ErrorInfo" - - type: object - properties: - status: - enum: - - 429 - code: - enum: - - QUOTA_EXCEEDED - - TOO_MANY_REQUESTS - examples: - GENERIC_429_QUOTA_EXCEEDED: - description: Request is rejected due to exceeding a business quota limit - value: - status: 429 - code: QUOTA_EXCEEDED - message: Out of resource quota. - GENERIC_429_TOO_MANY_REQUESTS: - description: Access to the API has been temporarily blocked due to rate or spike arrest limits being reached - value: - status: 429 - code: TOO_MANY_REQUESTS - message: Rate limit reached. - - Generic500: - description: Internal Server Error - headers: - x-correlator: - $ref: "#/components/headers/x-correlator" - content: - application/json: - schema: - allOf: - - $ref: "#/components/schemas/ErrorInfo" - - type: object - properties: - status: - enum: - - 500 - code: - enum: - - INTERNAL - examples: - GENERIC_500_INTERNAL: - description: Problem in Server side. Regular Server Exception - value: - status: 500 - code: INTERNAL - message: Unknown server error. Typically a server bug. - - Generic501: - description: Not Implemented - headers: - x-correlator: - $ref: "#/components/headers/x-correlator" - content: - application/json: - schema: - allOf: - - $ref: "#/components/schemas/ErrorInfo" - - type: object - properties: - status: - enum: - - 501 - code: - enum: - - NOT_IMPLEMENTED - examples: - GENERIC_501_NOT_IMPLEMENTED: - description: Service not implemented. The use of this code should be avoided as far as possible to get the objective to reach aligned implementations - value: - status: 501 - code: NOT_IMPLEMENTED - message: This functionality is not implemented yet. - - Generic502: - description: Bad Gateway - headers: - x-correlator: - $ref: "#/components/headers/x-correlator" - content: - application/json: - schema: - allOf: - - $ref: "#/components/schemas/ErrorInfo" - - type: object - properties: - status: - enum: - - 502 - code: - enum: - - BAD_GATEWAY - examples: - GENERIC_502_BAD_GATEWAY: - description: Internal routing problem in the Server side that blocks to manage the service properly - value: - status: 502 - code: BAD_GATEWAY - message: An upstream internal service cannot be reached. - - Generic503: - description: Service Unavailable - headers: - x-correlator: - $ref: "#/components/headers/x-correlator" - content: - application/json: - schema: - allOf: - - $ref: "#/components/schemas/ErrorInfo" - - type: object - properties: - status: - enum: - - 503 - code: - enum: - - UNAVAILABLE - examples: - GENERIC_503_UNAVAILABLE: - description: Service is not available. Temporary situation usually related to maintenance process in the server side - value: - status: 503 - code: UNAVAILABLE - message: Service Unavailable. - - Generic504: - description: Gateway Timeout - headers: - x-correlator: - $ref: "#/components/headers/x-correlator" - content: - application/json: - schema: - allOf: - - $ref: "#/components/schemas/ErrorInfo" - - type: object - properties: - status: - enum: - - 504 - code: - enum: - - TIMEOUT - examples: - GENERIC_504_TIMEOUT: - description: API Server Timeout - value: - status: 504 - code: TIMEOUT - message: Request timeout exceeded. + Must be a valid UUID as defined by RFC 4122 (versions 1-5) using only lowercase hexadecimal characters. + required: true + schema: + $ref: '#/components/schemas/UUID' + rebootRequestId: + name: rebootRequestId + in: path + required: true + schema: + $ref: '#/components/schemas/UUID' + description: ID of the Reboot Request. If the Reboot Request exists but the caller lacks permission to access it, the API returns 403. diff --git a/documentation/API_documentation/DeviceRebootRequest_User_Story.md b/documentation/API_documentation/DeviceRebootRequest_User_Story.md index 5bd2bce..da1e221 100644 --- a/documentation/API_documentation/DeviceRebootRequest_User_Story.md +++ b/documentation/API_documentation/DeviceRebootRequest_User_Story.md @@ -1,9 +1,9 @@ | **Item** | **Details** | |------------------------------|-------------| -| **Summary** | As a service owner or property manager, I want to issue reboot requests for my API provider-managed network access devices (such as gateways or mesh controllers) to recover from faulty network states or to perform administrative resets, ensuring reliable connectivity for tenants or guests. | +| **Summary** | As a service owner or property manager, I want to issue reboot requests for my API Provider-managed network access devices (such as gateways or mesh controllers) to recover from faulty network states or to perform administrative resets, ensuring reliable connectivity for tenants or guests. | | **Roles, Actors and Scope** | **Roles:** customer:user
**Actors:** Service owners, property managers, API providers.
**Scope:** Trouble to Resolution (T2R) - Issue immediate or scheduled reboot requests for specific devices. Retrieve status of previously created reboot requests. | | **Pre-conditions** | 1. The API consumer is onboarded and holds credentials with proper scopes (e.g., `reboot-requests:write`, optionally `devices:write`).
2. The devices are installed and managed by the API provider supporting reboot management. | | **Begins when** | The API client makes a `POST` request to `/reboot-requests` with a list of device IDs and an optional `atTime` to schedule the reboot. | -| **Ends when** | The reboot is executed by the API provider-managed device or the request is withdrawn. | +| **Ends when** | The reboot is executed by the API Provider-managed device or the request is withdrawn. | | **Post-conditions** | - The specified device(s) reboot, recovering connectivity or clearing transient faults.
- System logs are updated to reflect administrative action. | | **Exceptions** | - `400 Bad Request`: Malformed request body (e.g., invalid time format).
- `401 Unauthorized`: Access token issues.
- `403 Forbidden`: Lack of permission for target devices.
- `404 Not Found`: Specified reboot request or device ID does not exist.| \ No newline at end of file diff --git a/documentation/API_documentation/IsolatedNetworks_User_Story.md b/documentation/API_documentation/IsolatedNetworks_User_Story.md deleted file mode 100644 index 543e8b2..0000000 --- a/documentation/API_documentation/IsolatedNetworks_User_Story.md +++ /dev/null @@ -1,9 +0,0 @@ -| **Item** | **Details** | -|------------------------------|-------------| -| **Summary** | As a property manager or service owner, I want to create, modify, and delete logically isolated network configurations on API provider-managed network access devices (such as gateways or mesh Wi-Fi), so that I can securely segment networks for tenants, guests, or IoT devices, ensuring privacy and easy reconfiguration. | -| **Roles, Actors and Scope** | **Roles:** customer:user
**Actors:** Service owners, property managers, IoT integrators, API providers.
**Scope:** Order to Activate (O2A) - Create isolated networks with Wi-Fi access details (SSID, security mode, password). Configure which devices host these networks. Modify or delete existing networks as tenancy or use cases change. | -| **Pre-conditions** | 1. The API consumer is onboarded with the API provider and has received access credentials with proper scopes (e.g., `isolated-networks:write` and `devices:write`).
2. The service owner has one or more API provider-managed devices installed at the premises.
3. The API provider has implemented the NAM API with support for isolated network configuration. | -| **Begins when** | The API client makes a `POST` request to `/isolated-networks` to create a new isolated network (with optional expiration), providing access details (SSID, security mode). -| **Ends when** | The network configuration is created, updated, or removed and reflected on targeted devices. | -| **Post-conditions** | - New isolated networks are configured on specified devices, logically segmenting LAN traffic.
- Obsolete networks are removed from devices and automatically deleted if no longer assigned. | -| **Exceptions** | - `400 Bad Request`: Invalid parameters (e.g., malformed SSID, unsupported security mode).
- `401 Unauthorized`: Invalid or expired access token.
- `403 Forbidden`: Insufficient scope or revoked client authorization.
- `404 Not Found`: Nonexistent network or device ID. | \ No newline at end of file diff --git a/documentation/API_documentation/README.MD b/documentation/API_documentation/README.MD index 37aa0ff..f5a82cf 100644 --- a/documentation/API_documentation/README.MD +++ b/documentation/API_documentation/README.MD @@ -1 +1,57 @@ -This README.MD can be deleted when the first file is added to this directory. +# CAMARA User Story Guidance + +This document summarizes how to create or modify CAMARA-aligned User Stories using the **Commonalities User Story Template** and how to determine the correct **Scope** value based on the **TM Forum NaaS (TMF 909A)** lifecycle definitions. + +--- + +## 1. Authoritative Sources + +Any information in this guide is derived from the following authoritative sources: + +| Source | Description | Link | +|--------|--------------|------| +| **CAMARA Commonalities – User Story Template** | Canonical template defining fields, structure, and allowed values (Roles, Scope, etc.). | [github.com/camaraproject/Commonalities/documentation/Userstory-template.md](https://github.com/camaraproject/Commonalities/blob/main/documentation/Userstory-template.md) | +| **CAMARA Commonalities – Guidelines** | Explains how Commonalities artifacts (User Stories, API Guidelines, etc.) are structured. | [camaraproject.org/commonalities](https://camaraproject.org/commonalities/) | +| **TM Forum TMF 909A – NaaS API Component Suite Profile v1.5** | Defines the lifecycle areas used for the “Scope” field. | [TM Forum TMF 909A – NaaS API Component Suite Profile](https://engage.tmforum.org/HigherLogic/System/DownloadDocumentFile.ashx?DocumentFileKey=70781cfc-1ebb-4ef9-b728-44b34e9c14a1) | +| **TM Forum Open APIs** | APIs referenced for each lifecycle area (TMF 633, 640, 645, 653, 656, 677). | [tmforum.org/open-apis](https://www.tmforum.org/open-apis/) | + +Start with the [CAMARA Commonalities – User Story Template](https://github.com/camaraproject/Commonalities/blob/main/documentation/Userstory-template.md) for a comprehensive understanding of user story structure and requirements. From there, you will note a `ReferenceArchitecture` powerpoint is mentioned; this includes slides that summarize the alignment with TM Forum lifecycles, which is further detailed in Section 3 of this document. + +--- + +## 2. User Story Template Overview + +Each CAMARA User Story should include: + +| Field | Description | Guidance | +|-------|--------------|-----------| +| **Title / Summary** | “As a \, I want \ so that \.” | User-centric phrasing. | +| **Roles** | Acceptable values: `customer:user`, `customer:administrator`, `customer:business manager` (from Commonalities template). | Choose based on the actor’s function and access level. | +| **Actor(s)** | Entity or system executing or triggering the story (e.g., API Consumer, API Provider, Service Owner). | Prefer roles over specific implementations. | +| **Scope** | Lifecycle area(s) impacted. See Section 3 below. | Select **one or more** of: Design time, P2O, O2A, U2C, T2R. | +| **Pre-conditions / Begins when** | Required system or business state before the story starts. | Often references catalog or active service. | +| **Steps** | Numbered flow of actions. | Keep technology-neutral. | +| **Post-conditions / Ends when** | Expected outcome or state. | Clarify data, service, or operational result. | +| **Exceptions** | Deviations or failure modes. | Include both business and technical exceptions if relevant. | + +--- + +## 3. Scope Reference (Lifecycle Areas) + +The **Scope** field classifies a user story according to the TM Forum NaaS (TMF 909A) lifecycle model. +Use this section to determine where a story fits. + +| Scope | TM Forum Reference | Summary | Typical APIs / Activities | +|--------|--------------------|----------|----------------------------| +| **Design Time** | TMF 909A § 2.1.5 (Service Catalog) | “Concept-to-Market” activities defining new service specifications. Used for retrieving, creating, or updating service specs prior to runtime. | TMF 633 Service Catalog Management | +| **Prospect to Order (P2O)** | TMF 909A § 2.1.2 | Evaluate what products or services can be offered to a customer. Includes availability checks, feasibility analysis, and resource reservation. | TMF 645 Service Qualification | +| **Order to Activate (O2A)** | TMF 909A § 2.1.1 | Fulfil and activate ordered services, including in-flight modification, suspension, or removal. Covers the operational lifecycle of a service instance. | TMF 640 Activation & Configuration | +| **Usage to Cash (U2C)** | TMF 909A § 2.1.4 | Measure and report service usage for billing or quota management. Includes retrieval, periodic reporting, and threshold notifications. | TMF 677 Usage Consumption | +| **Trouble to Resolution (T2R)** | TMF 909A § 2.1.3 | Monitor, diagnose, and restore services when faults occur. Includes testing, problem creation, updates, and closure. | TMF 656 Service Problem Mgmt, TMF 653 Service Test | + +> **Tip:** +> - If the story involves designing or publishing a service → **Design Time** +> - If it checks availability or feasibility before order → **P2O** +> - If it provisions or modifies active services → **O2A** +> - If it deals with usage or quotas → **U2C** +> - If it handles incidents or assurance → **T2R** diff --git a/documentation/API_documentation/TrustDomainsUser_Story.md b/documentation/API_documentation/TrustDomainsUser_Story.md new file mode 100644 index 0000000..a4016c2 --- /dev/null +++ b/documentation/API_documentation/TrustDomainsUser_Story.md @@ -0,0 +1,10 @@ +| **Item** | **Details** | +|-----------|-------------| +| **Summary** | As a **service owner or API Consumer**, I want to create, modify, and delete **logically isolated network configurations** (Trust Domains) on **API Provider-managed network access devices** (such as gateways or mesh Wi-Fi), defining both network access details and associated policies (such as device limits, bandwidth, or egress rules), so that I can securely segment and govern connectivity for tenants, guests, or IoT devices with predictable behavior and lifecycle control. | +| **Roles, Actors, and Scope** | **Roles:** `customer:user`.
**Actors:** Service owners, API Consumers, IoT integrators, API providers.
**Scope:** **Order to Activate (O2A)** — Covers provisioning, modification, and removal of active network configurations. Trust Domain management corresponds to TM Forum **TMF 909A § 2.1.1 “Order to Activate”**, which governs service activation and configuration actions. | +| **Pre-conditions** | 1. The API Consumer has been onboarded with the API provider and obtained valid access credentials with appropriate scopes (e.g., `network-access-management:trust-domains:write`).
2. The service owner has one or more registered API-provider-managed devices at their premises.
3. The API provider has implemented the **Network Access Management (NAM)** API supporting Trust Domain configuration. | +| **Begins when** | The API Consumer sends a `POST` request to `/trust-domains` to create a new Trust Domain (optionally including expiration), providing Wi-Fi access details such as SSID, security mode, and credentials, or to `PATCH`/`DELETE` for modification or removal. | +| **Ends when** | The requested Trust Domain is created, updated, or deleted, and the configuration change is successfully reflected on the associated network access devices. | +| **Post-conditions** | - New Trust Domains are provisioned and active on designated or inferred network devices, enforcing logical traffic segmentation.
- Updated configurations replace previous credentials or policies.
- Trust Domains that are no longer assigned to any device are automatically removed. | +| **Exceptions** | - **400 Bad Request:** Invalid request parameters (e.g., malformed SSID, unsupported security mode).
- **401 Unauthorized:** Missing, invalid, or expired access token.
- **403 Forbidden:** Caller lacks sufficient authorization scope or role.
- **404 Not Found:** Referenced device or Trust Domain ID does not exist.
- **409 Conflict:** Attempt to delete a non-removable or in-use Trust Domain. | +| **References** | - [CAMARA Commonalities – User Story Template](https://github.com/camaraproject/Commonalities/blob/main/documentation/Userstory-template.md)
- [TM Forum TMF 909A v1.5 § 2.1.1 – Order to Activate](https://projects.tmforum.org/wiki/display/API/TMF640+Activation+and+Configuration+API+REST+Specification)| diff --git a/documentation/API_documentation/network-access-management-API-Readiness-Checklist.md b/documentation/API_documentation/network-access-management-API-Readiness-Checklist.md index 3325800..6ee276e 100644 --- a/documentation/API_documentation/network-access-management-API-Readiness-Checklist.md +++ b/documentation/API_documentation/network-access-management-API-Readiness-Checklist.md @@ -1,22 +1,22 @@ # API Readiness Checklist -Checklist for network-access-management 0.1.0-alpha.1 in r1.0-rc.1. +Checklist for network-access-management 0.1.0-alpha.1 in r1.1. | Nr | API release assets | alpha | release-candidate | initial
public | stable
public | Status | Reference information | |----|----------------------------------------------|:-----:|:-----------------:|:-------:|:------:|:----:|:---------------:| | 1 | API definition | M | M | M | M | Y | [relative link](../../code/API_definitions/network-access-management.yaml) | -| 2 | Design guidelines from Commonalities applied | O | M | M | M | Y | r2.3 | -| 3 | Guidelines from ICM applied | O | M | M | M | Y | r2.3 | +| 2 | Design guidelines from Commonalities applied | O | M | M | M | Y | r3.4 | +| 3 | Guidelines from ICM applied | O | M | M | M | Y | r3.3 | | 4 | API versioning convention applied | M | M | M | M | Y | | | 5 | API documentation | M | M | M | M | Y | inline in yaml | | 6 | User stories | O | O | O | M | N | | | 7 | Basic API test cases & documentation | O | M | M | M | N | | | 8 | Enhanced API test cases & documentation | O | O | O | M | N | | | 9 | Test result statement | O | O | O | M | N | | -| 10 | API release numbering convention applied | M | M | M | M | Y | | -| 11 | Change log updated | M | M | M | M | Y | [relative link](../../CHANGELOG.md) | +| 10 | API release numbering convention applied | M | M | M | M | N | | +| 11 | Change log updated | M | M | M | M | N | [relative link](../../CHANGELOG.md) | | 12 | Previous public release was certified | O | O | O | M | N | | -| 13 | API description (for marketing) | O | O | M | M | | [wiki link](https://lf-camaraproject.atlassian.net/wiki/spaces/CAM/pages/81166949/NetworkAccessManagement+API+description) | +| 13 | API description (for marketing) | O | O | M | M | N | [wiki link](https://lf-camaraproject.atlassian.net/wiki/spaces/CAM/pages/81166949/NetworkAccessManagement+API+description) | To fill the checklist: