Skip to content

Adding description of the MaxNumberOfDevices parameter #88

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
tlohmar wants to merge 4 commits into
base: main
Choose a base branch
from
+44 −4
Open

Adding description of the MaxNumberOfDevices parameter #88

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
4141e52
Adding considerations on MaxNumberOfDevices
tlohmar Nov 30, 2025
c5108f6
Clarification, that all devices are considered.
tlohmar Dec 12, 2025
4a6fa4a
Adding support for 429 Status Code.
tlohmar Jan 26, 2026
f8109b3
Adding more information, when the 429 QUOTA_EXCEEDED error code is pr…
tlohmar Jan 29, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 35 additions & 1 deletion code/API_definitions/dedicated-network-accesses.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,7 @@ info:

- If the subject cannot be identified from the access token and the optional `device` object is not included in the request, then the server will return an error with the `422 MISSING_IDENTIFIER` error code.
- If the subject can be identified from the access token and the optional `device` object is also included in the request, then the server will return an error with the `422 UNNECESSARY_IDENTIFIER` error code. This will be the case even if the same `device` is identified by these two methods, as the server is unable to make this comparison.
- If the number of devices with access to the network exceeds the `maxNumberOfDevices`, the API provider will provide a `429 QUOTA_EXCEEDED` error code.

# Creating a device access

Expand Down Expand Up @@ -162,7 +163,8 @@ paths:
$ref: "#/components/responses/Generic404"
"422":
$ref: "#/components/responses/Generic422"

"429":
$ref: "#/components/responses/Generic429"
/accesses/{accessId}:
get:
tags:
Expand Down Expand Up @@ -596,3 +598,35 @@ components:
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.
12 changes: 9 additions & 3 deletions code/API_definitions/dedicated-network-profiles.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,9 +11,15 @@ info:

A Network Profile represents a predefined set of network capabilities and performance characteristics that can be applied when creating a Network. It enables API Consumers to understand the capabilities they can expect when using the reserved network connectivity resources. A Network Profile is a validated, supported configuration that has been pre-approved between the API Provider and API Consumer.

A Network Profile contains information about the maximum number of devices allowed, the aggregated throughput to be provided, and a set of allowed QoS Profiles that devices can use when having access to the Dedicated Network. The concept of named QoS Profiles is re-used from the [QualityOnDemand](https://github.com/camaraproject/QualityOnDemand) API family.
* An API provider may offer the QualityOnDemand `qos-profiles` API for resolving a QoS Profile name into characteristics of a specific QoS profile.
* When multiple QoS Profiles are supported within one Network Profile, the QualityOnDemand `quality-on-demand` API may be used to assign one of the available QoS profiles to a specific device while the Network is in ACTIVATED state .
A Network Profile contains information about the maximum number of devices allowed, the aggregated throughput to be provided, and a set of allowed QoS Profiles that devices can use when having access to the Dedicated Network. The concept of named QoS Profiles is re-used from the [QualityOnDemand](https://github.com/camaraproject/QualityOnDemand) API family. An API provider may offer the QualityOnDemand `qos-profiles` API for resolving a QoS Profile name into characteristics of a specific QoS profile.

Network Profiles are designed to support different use-cases and should contain the matching `qos-profile` combinations. Generally, two types of Network Profiles can be identified
* Network Profiles containing only a `defaultQosProfile`
* Network Profiles containing one or more additional `qos-profile`s with the `qosProfiles` array. When multiple QoS Profiles are supported within one Network Profile, the QualityOnDemand `quality-on-demand` API may be used to assign one of the available QoS profiles to a specific device while the Network is in `ACTIVATED` state

Devices are not neccessarily using connectivity continuously. The value of the `maxNumberOfDevices` parameter should be set _generous_, considering that not all devices using connectivity simultaneously and/or continuously.

The parameters `aggregatedUlThroughput` and `aggregatedDlThroughput` define the (hard) limits of simultaneous connectivity usage, ie. sum of all traffic pertaining all devices using the available QoS profiles.

A detailed description of the individual parameters may be included within the _terms and conditions_ (outside of scope for the API).

Expand Down
Loading