Adding description of the MaxNumberOfDevices parameter

code/API_definitions/dedicated-network-accesses.yaml

@@ -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 is equal to or exceeds the 'maxNumberOfDevices', the API provider will provide a `429 QUOTA_EXCEEDED` error code.
 
     # Creating a device access
 
@@ -211,7 +212,8 @@ paths:
           $ref: "#/components/responses/Generic409"
         "422":
           $ref: "#/components/responses/Generic422"
-
+        "429":
+          $ref: "#/components/responses/Generic429"
   /accesses/{accessId}:
     get:
       tags:
@@ -908,6 +910,38 @@ 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.
 
   examples:
 

code/API_definitions/dedicated-network-profiles.yaml

@@ -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).