diff --git a/code/API_definitions/dedicated-network-profiles.yaml b/code/API_definitions/dedicated-network-profiles.yaml index 86ad313..6e3cc13 100644 --- a/code/API_definitions/dedicated-network-profiles.yaml +++ b/code/API_definitions/dedicated-network-profiles.yaml @@ -5,21 +5,21 @@ info: # Introduction - This API allows for discovering available network profiles, which are offered by the network provider to be used in conjunction of the Dedicated Network API. Network profiles describe the capabilities and performance targets of a dedicated network. For more information about the Dedicated Networks APIs, see [link](). + This API allows for discovering available network profiles, which are offered by the network provider to be used in conjunction of the Dedicated Network API. Network profiles describe the capabilities and performance targets of a dedicated network. + + For more information about the Dedicated Network APIs, see the _GeneralDescription_ document in the Dedicated Networks [repository](https://github.com/camaraproject/DedicatedNetworks/). # Network Profiles 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. + 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 (including a default QoS Profile) 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 + A Network Profile is designed to be flexible to support use-cases which may require different `qos-profile` combinations. - 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. + Devices are not necessarily 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. + The parameters `aggregatedUlThroughput` and `aggregatedDlThroughput` define the (hard) limits of simultaneous connectivity usage, i.e. 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). @@ -114,7 +114,7 @@ paths: - $ref: "../common/CAMARA_common.yaml#/components/parameters/x-correlator" responses: '200': - description: List of available network profiles + description: List of available network profiles matching the given criteria and in the requested page (can be empty) headers: x-correlator: $ref: "../common/CAMARA_common.yaml#/components/headers/x-correlator" @@ -155,7 +155,7 @@ paths: - $ref: "../common/CAMARA_common.yaml#/components/parameters/x-correlator" responses: '200': - description: List of available network profiles + description: Information about the network profile headers: x-correlator: $ref: "../common/CAMARA_common.yaml#/components/headers/x-correlator" @@ -211,6 +211,7 @@ components: name: description: A human-readable name to describe the network profile type: string + minLength: 1 maxLength: 1024 maxNumberOfDevices: description: The maximum number of devices that can simultaneously use and share the dedicated network under this profile up to the limits set by the profile's performance characteristics @@ -253,6 +254,9 @@ components: maximum: 1024 unit: $ref: "#/components/schemas/BitRateUnitEnum" + required: + - value + - unit BitRateUnitEnum: description: Units of bitrate @@ -398,9 +402,3 @@ components: 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. diff --git a/code/API_definitions/dedicated-network.yaml b/code/API_definitions/dedicated-network.yaml index 10c9106..0f0d7c8 100644 --- a/code/API_definitions/dedicated-network.yaml +++ b/code/API_definitions/dedicated-network.yaml @@ -33,12 +33,12 @@ info: The API returns a networkId. The networkId is a unique identifier of the network, which remains unchanged during its lifetime. The networkId is required when creating Device Accesses. - Initially, the created network is in `REQUESTED` state. The network is only usable when the network is in `ACTIVATED` state. Find a detailed description of the network states [here](). + Initially, the created network is in `REQUESTED` state. The network is only usable when the network is in `ACTIVATED` state. Find a detailed description of the network states [here](../../documentation/API_documentation/DedicatedNetworks_GeneralDescription.md#states-of-the-network). # Querying one or more Networks - All available network of the API consumer can be queried by performing a `GET` operation on the `/networks` endpoint. The query can be filtered for networks matching a certain name. + All available networks of the API consumer can be queried by performing a `GET` operation on the `/networks` endpoint. The query can be filtered for networks matching a certain name. A specific network of the API consumer can be queried by performing a `GET` operation on the `/networks/{networkId}` endpoint, where the networkId has been obtained during the _create_ procedure. @@ -193,7 +193,7 @@ paths: - notificationsBearerAuth: [] responses: '201': - description: Reception acknowlegement a dedicated network request + description: Successful creation of a dedicated network headers: x-correlator: $ref: "../common/CAMARA_common.yaml#/components/headers/x-correlator" @@ -214,6 +214,10 @@ paths: $ref: "#/components/responses/Generic401" "403": $ref: "#/components/responses/Generic403" + '404': + $ref: "#/components/responses/Generic404" + '422': + $ref: "#/components/responses/UnprocessableServiceTime422" /networks/{networkId}: get: @@ -405,10 +409,10 @@ components: NetworkStatus: description: | The current status of the requested network. The status can be one of the following: - * `REQUESTED` - The DN is requested, but not approved. Possible transitions to RESERVED, ACTIVATED and TERMINATED states - * `RESERVED` - Request is accepted by the CSP (CSP has committed the requested resources), but the Network cannot be used (outside of requested time-window) - * `ACTIVATED` - Network turns from reserved into Activated. Now, devices with access can use the network. Possible transitions to RESERVED or TERMINATED states - * `TERMINATED` - The Network resource is used and up for deletion. The API does not allow any action (except delete). + * `REQUESTED` - The network is requested, but not approved. Possible transitions to RESERVED, ACTIVATED and TERMINATED states. + * `RESERVED` - Request is accepted by the CSP (CSP has committed the requested resources), but the Network cannot be used (outside of requested time-window). Possible transitions to ACTIVATED and TERMINATED states. + * `ACTIVATED` - When the network is activated devices with access can use it. Transitions to TERMINATED state. + * `TERMINATED` - The network cannot be used any more and is up for deletion. The API does not allow any further action except deletion. type: string enum: @@ -586,7 +590,9 @@ components: code: enum: - NOT_FOUND - - IDENTIFIER_NOT_FOUND + - DEDICATED_NETWORK.QOS_PROFILE_NAME_NOT_FOUND + - DEDICATED_NETWORK.NETWORK_PROFILE_IDENTIFIER_NOT_FOUND + - DEDICATED_NETWORK.SERVICE_AREA_IDENTIFIER_NOT_FOUND examples: GENERIC_404_NOT_FOUND: description: Resource is not found @@ -594,12 +600,24 @@ components: 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 + GENERIC_404_QOS_PROFILE_NAME_NOT_FOUND: + description: Requested QoS profile name is not found + value: + status: 404 + code: DEDICATED_NETWORK.QOS_PROFILE_NAME_NOT_FOUND + message: QoS profile name not found. + GENERIC_404_NETWORK_PROFILE_IDENTIFIER_NOT_FOUND: + description: Requested network profile identifier is not found + value: + status: 404 + code: DEDICATED_NETWORK.NETWORK_PROFILE_IDENTIFIER_NOT_FOUND + message: Network profile identifier not found. + GENERIC_404_SERVICE_AREA_IDENTIFIER_NOT_FOUND: + description: Requested service area identifier is not found value: status: 404 - code: IDENTIFIER_NOT_FOUND - message: Device identifier not found. + code: DEDICATED_NETWORK.SERVICE_AREA_IDENTIFIER_NOT_FOUND + message: Service area identifier not found. Generic410: description: Gone @@ -627,6 +645,32 @@ components: code: GONE message: Access to the target resource is no longer available. + UnprocessableServiceTime422: + description: Unprocessable Service Time due to incorrect start and end times + headers: + x-correlator: + $ref: "../common/CAMARA_common.yaml#/components/headers/x-correlator" + content: + application/json: + schema: + allOf: + - $ref: "../common/CAMARA_common.yaml#/components/schemas/ErrorInfo" + - type: object + properties: + status: + enum: + - 422 + code: + enum: + - DEDICATED_NETWORK.INCORRECT_SERVICE_TIME + examples: + DEDICATED_NETWORK_422_INCORRECT_SERVICE_TIME: + description: The request is syntactically correct but the service time in the request could not be processed successfully. + value: + status: 422 + code: DEDICATED_NETWORK.INCORRECT_SERVICE_TIME + message: Requested service time could not be processed successfully. + examples: NETWORK_STATUS_CHANGED_EXAMPLE: diff --git a/documentation/API_documentation/DedicatedNetworks_GeneralDescription.md b/documentation/API_documentation/DedicatedNetworks_GeneralDescription.md index 80b41ae..778917c 100644 --- a/documentation/API_documentation/DedicatedNetworks_GeneralDescription.md +++ b/documentation/API_documentation/DedicatedNetworks_GeneralDescription.md @@ -193,10 +193,11 @@ stateDiagram-v2 RESERVED --> ACTIVATED: Service Time reached ACTIVATED --> TERMINATED: Service Time expires REQUESTED --> ACTIVATED: Use is confirmed (Service Time already reached) - RESERVED --> TERMINATED: Failed to reserve resources + REQUESTED --> TERMINATED: Failed to reserve resources + RESERVED --> TERMINATED: Unexpected failure ``` -Explainations +Explanations - A network in REQUESTED state is not (yet) committed by the Network Provider. - A network in RESERVED state is committed to be available for use during the Service Time by the Network Provider. @@ -209,6 +210,8 @@ Explainations - The network may enter the TERMINATED state directly after the REQUESTED state if the API Provider could not complete the resource reservation. +- The network may enter the TERMINATED state directly after the RESERVED state if the API Provider could not keep the reserved resources due to an unexpected failure. + - A network in TERMINATED state cannot be modified anymore and should be deleted. If not deleted by the API Consumer, the representing HTTP resource (URL) may be removed by the API Provider. ## States of device's access to the network