diff --git a/code/API_definitions/dedicated-network-areas.yaml b/code/API_definitions/dedicated-network-areas.yaml new file mode 100644 index 0000000..c6ab073 --- /dev/null +++ b/code/API_definitions/dedicated-network-areas.yaml @@ -0,0 +1,433 @@ +openapi: 3.0.3 +info: + title: Dedicated Network - Areas + description: | + + # Introduction + + This API allows for discovering available network service areas, which are the geographical areas offered by the network provider where consitent coverage according to indicated network profile(s) and QoS profiles is provided, and which is to be used in conjunction with the Dedicated Network API. + + For more information about the Dedicated Network APIs, see the _GeneralDescription_ document in the Dedicated Networks [repository](https://github.com/camaraproject/DedicatedNetworks/). + + # Network Service Areas + + A Network Service Area represents a geographical area with coverage consistent with the characteristics of the network profiles and the QoS profiles supported in the area. It enables API Consumers to select the geographical area where they can expect to consume the reserved network connectivity resources. A Network Service Area may have been pre-agreed between the API Provider and API Consumer. + + A Network Service Area contains information about its geographical boundaries and the supported network profiles and QoS profiles. It is uniquely identified by a UUID identifier and it contains a human readable name and description. + + # Network Service Areas API + + The key characteristics of the API include: + + - Network Service Areas are read-only resources from the API Consumer perspective + + - They are discoverable by POST operations + + - They are readable by GET operations + + - Each Network Service Area has a unique identifier (areaId) + + - The areaId serves as a reference when creating a Dedicated Network + + - The API returns only Network Service Areas that the API Consumer is eligible to use based on their agreements + + # 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. + + # Querying one or more Areas + + All available network service areas of the API consumer can be queried by performing a `POST` operation on the `/retrieve-service-areas` endpoint. + + The API Consumer may provide the following input parameters as search criteria which must be matched for the network service area to be returned: + + - `atLocation` - to return the network service areas available at the given geographical location + + - `overlappingArea` - to return the network service areas whose geographical area overlaps (but does not fully cover) the input geographical area, where the input geographical area may be a circle or polygon + + - `coveringArea` - to return the network service areas whose geographical area fully covers the input geographical area will be returned, where the input geographical area may be a circle or polygon + + - `byName` - to return the network service areas with a name matching exactly the input string + + - `byNetworkProfileId` - to return the network service areas which support the input network profile identifier + + - `byQosProfileName` - to return the network service areas which support the input QoS profile name + + A specific network service area of the API consumer can be queried by performing a `GET` operation on the `/areas/{areaId}` endpoint. + + license: + name: Apache 2.0 + url: https://www.apache.org/licenses/LICENSE-2.0.html + version: wip + x-camara-commonalities: 0.6 +servers: + - url: "{apiRoot}/dedicated-network-areas/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` +paths: + /retrieve-service-areas: + post: + tags: + - Areas + summary: Retrieve dedicated network service areas, filtered by additional search criteria + operationId: retrieveNetworkServiceAreas + requestBody: + description: Parameters to query service areas + content: + application/json: + schema: + $ref: "#/components/schemas/RetrieveServiceAreasRequest" + required: true + responses: + '200': + description: List of available dedicated network service areas + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/ServiceArea' + '400': + $ref: "#/components/responses/Generic400" + "401": + $ref: "#/components/responses/Generic401" + "403": + $ref: "#/components/responses/Generic403" + "404": + $ref: "#/components/responses/Generic404" + + /areas/{areaId}: + get: + tags: + - Areas + summary: Read a dedicated network service area + operationId: readNetworkServiceArea + parameters: + - name: areaId + in: path + required: true + schema: + $ref: "#/components/schemas/ServiceAreaId" + - $ref: "#/components/parameters/x-correlator" + responses: + '200': + description: Information about the dedicated network service area + content: + application/json: + schema: + $ref: '#/components/schemas/ServiceArea' + '400': + $ref: "#/components/responses/Generic400" + "401": + $ref: "#/components/responses/Generic401" + "403": + $ref: "#/components/responses/Generic403" + "404": + $ref: "#/components/responses/Generic404" + +components: + + 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" + + schemas: + XCorrelator: + type: string + pattern: ^[a-zA-Z0-9-_:;.\/<>{}]{0,256}$ + example: "b4333c46-49c0-4f62-80d7-f0ef930f1c46" + + NetworkProfileId: + type: string + + QosProfileName: + description: | + A unique name for identifying a specific QoS profile. + This may follow different formats depending on the service providers implementation. + Some options addresses: + - A UUID style string + - Support for predefined profiles QOS_S, QOS_M, QOS_L, and QOS_E + - A searchable descriptive name + The set of QoS Profiles that an operator is offering can be retrieved by means of the QoS Profile API. + type: string + example: QCI_1_voice + minLength: 3 + maxLength: 256 + format: string + pattern: "^[a-zA-Z0-9_.-]+$" + + ServiceAreaId: + type: string + format: uuid + + RetrieveServiceAreasRequest: + description: Request object to retrieve service areas that match all the given properties + type: object + properties: + atLocation: + $ref: "#/components/schemas/Point" + overlappingArea: + $ref: "#/components/schemas/Area" + coveringArea: + $ref: "#/components/schemas/Area" + byName: + type: string + byNetworkProfileId: + $ref: "#/components/schemas/NetworkProfileId" + byQosProfileName: + $ref: "#/components/schemas/QosProfileName" + + ServiceArea: + description: Common attributes of a service area, i.e. where the dedicated network service is supported + properties: + id: + $ref: '#/components/schemas/ServiceAreaId' + name: + type: string + description: + type: string + area: + $ref: '#/components/schemas/Area' + networkProfiles: + description: Dedicated network profiles which are supported in this area. + type: array + items: + $ref: "#/components/schemas/NetworkProfileId" + minItems: 1 + qosProfiles: + description: Qos Profiles which are supported in this area. + type: array + items: + $ref: '#/components/schemas/QosProfileName' + minItems: 1 + required: + - id + - area + anyOf: + - required: + - networkProfiles + - required: + - qosProfiles + + Area: + description: Common attributes of a geographical area, base schema for all area types + 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 + properties: + center: + $ref: "#/components/schemas/Point" + radius: + type: integer + description: | + Radius from `center` in meters. + minimum: 1 + maximum: 200000 + required: + - center + - radius + + 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 + + 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 + + responses: + Generic400: + description: Bad Request + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + 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: + $ref: "#/components/schemas/ErrorInfo" + examples: + GENERIC_401_UNAUTHENTICATED: + description: Request cannot be authenticated + value: + status: 401 + code: UNAUTHENTICATED + message: Request not authenticated due to missing, invalid, or expired credentials. + GENERIC_401_AUTHENTICATION_REQUIRED: + description: New authentication is needed, authentication is no longer valid + value: + status: 401 + code: AUTHENTICATION_REQUIRED + message: New authentication is required. + + Generic403: + description: Forbidden + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + 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: + $ref: "#/components/schemas/ErrorInfo" + examples: + GENERIC_404_NOT_FOUND: + description: Resource is not found + value: + status: 404 + code: NOT_FOUND + message: The specified resource is not found. + + Generic410: + description: Gone + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + 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. diff --git a/code/API_definitions/dedicated-network.yaml b/code/API_definitions/dedicated-network.yaml index 83981fc..7f2e3ca 100644 --- a/code/API_definitions/dedicated-network.yaml +++ b/code/API_definitions/dedicated-network.yaml @@ -18,9 +18,9 @@ info: The API Consumer needs to provide the following input parameters to create a network: - - the chosen Network Profile (profileId) + - the chosen Network Profile (networkProfileId) or QoS profile (qosProfileName). The choice is between a Network Profile (which contains properties like maximum number of devices, aggregated throughput, a list of supported QOS profiles, and a default QoS profile) and a QoS Profile which is equivalent to a simplified Network Profile for a single device, with just a default QoS profile, and with the aggregated throughput corresponding to the throughput defined by the QoS Profile. - - the Service Area + - the Service Area (serviceAreaId) - the service start and end times (Service Time). @@ -265,16 +265,38 @@ components: type: string format: uuid + QosProfileName: + description: | + A unique name for identifying a specific QoS profile. + This may follow different formats depending on the service providers implementation. + Some options addresses: + - A UUID style string + - Support for predefined profiles QOS_S, QOS_M, QOS_L, and QOS_E + - A searchable descriptive name + The set of QoS Profiles that an operator is offering can be retrieved by means of the QoS Profile API. + type: string + example: QCI_1_voice + minLength: 3 + maxLength: 256 + format: string + pattern: "^[a-zA-Z0-9_.-]+$" + + ServiceAreaId: + type: string + format: uuid + BaseNetworkInfo: description: Common attributes of a dedicated network type: object properties: - profileId: + networkProfileId: $ref: '#/components/schemas/NetworkProfileId' + qosProfileName: + $ref: '#/components/schemas/QosProfileName' serviceTime: $ref: '#/components/schemas/ServiceTime' - serviceArea: - $ref: '#/components/schemas/Area' + serviceAreaId: + $ref: '#/components/schemas/ServiceAreaId' sink: description: The address to which events shall be delivered using the selected protocol. type: string @@ -283,9 +305,13 @@ components: sinkCredential: $ref: '#/components/schemas/SinkCredential' required: - - profileId - serviceTime - - serviceArea + - serviceAreaId + oneOf: + - required: + - networkProfileId + - required: + - qosProfileName NetworkInfo: description: Current dedicated network information @@ -399,38 +425,6 @@ components: - start - end - Area: - description: Base schema for all areas - type: object - properties: - areaType: - $ref: "#/components/schemas/AreaType" - required: - - areaType - discriminator: - propertyName: areaType - mapping: - AREANAME: "#/components/schemas/AreaName" - - AreaType: - type: string - description: | - Type of this area. - AREANAME - The area is defined by an area name - enum: - - AREANAME - - AreaName: - description: Name of a predefined area - allOf: - - $ref: "#/components/schemas/Area" - - type: object - required: - - areaName - properties: - areaName: - type: string - SinkCredential: type: object properties: diff --git a/documentation/API_documentation/DedicatedNetworks_GeneralDescription.md b/documentation/API_documentation/DedicatedNetworks_GeneralDescription.md index 905c77b..d05065e 100644 --- a/documentation/API_documentation/DedicatedNetworks_GeneralDescription.md +++ b/documentation/API_documentation/DedicatedNetworks_GeneralDescription.md @@ -45,9 +45,10 @@ The APIs are summarized in the table below followed by a brief description. Deta | ---- | ------- | ----| | Dedicated Network API | Reservation and lifecycle management of network connectivity resources for dedicated use. | A Dedicated Network is a logical resource and is used to embody the reservation of network connectivity resources in the physical network. Initiating a new reservation request using this API results in a new Dedicated Network resource being created. The Dedicated Network undergoes various lifecycle States including REQUESTED, RESERVED, ACTIVATED and TERMINATED. Reservation of resources occurs based on the selected Network Profile, duration when the reservation is needed (Service Time) and geographical areas where the service is needed (Service Area). | | Dedicated Network Profiles API | Discovery of predefined set of network capabilities and performance characteristics | A Network Profile represents a predefined set of network capabilities and performance characteristics that can be applied when creating dedicated networks. Each profile represents a validated, supported configuration that has been pre-approved in the _terms and conditions_ between the API Provider and API Consumer. | +| Dedicated Network Areas API | Discovery of network service areas with support for network profiles and QoS profiles | A Network Service Area represents a geographical area with coverage consistent with one or more network profiles and/or one or more QoS profiles. It enables API Consumers to select the geographical area where they can expect to consume the reserved network connectivity resources. A Network Service Area may have been pre-agreed between the API Provider and API Consumer in the _terms and conditions_ between the API Provider and API Consumer. | | Dedicated Network Accesses API | Managing access to the Dedicated Network, i.e., controlling which devices may benefit from the reserved resources and capabilities | A Device Access represents the permission for a specific device to use a Dedicated Network's reserved connectivity resources. The usage of resources can be tailored to each device within the constraints of the applicable Network Profile.
The access for devices to the network can only be managed when the Network is created and not in the TERMINATED [state](#states-of-the-network). | -The Accesses and the Network Profile re-use the concept of named QoS Profiles from [QualityOnDemand](https://github.com/camaraproject/QualityOnDemand) for describing connectivity performance characteristics. An API provider may offer the `qos-profiles` API for resolving a QoS Profile name into characteristics of a specific QoS profile. +The Accesses and the Network Profile re-use the concept of named QoS Profiles from [QualityOnDemand](https://github.com/camaraproject/QualityOnDemand) for describing connectivity performance characteristics. An API provider may offer the `qos-profiles` API for resolving a QoS Profile name into characteristics of a specific QoS profile. When multiple QoS profiles are defined within a Network Profile, the API Consumer may either statically assign a different QoS profile (from the set of QoS profiles) for each device access or may dynamically create QoS Sessions using the QualityOnDemand `quality-on-demand` API. The API Consumer may also restict the list of possible QoS Profiles within a Device Access. @@ -59,11 +60,13 @@ A high-level sequence of steps involved when using Dedicated Network APIs is dep ```mermaid graph TD 0[Complete Pre-requisites] - A[Choose Dedicated Network Profile] + 1[Choose Dedicated Network Service Area] + A[Choose Dedicated Network Profile or QoS Profile] B[Create a Dedicated Network] C[Create Device Accesses] D[Allowed devices can use reserved network connectivity resources] - 0 --> A + 0 --> 1 + 1 --> A A --> B B --> C C --> D @@ -77,7 +80,7 @@ An API Provider may provide a catalog where API Consumers can get an overview of The API Provider may also offer a procedure for requesting additional customization, for example, additional Service Areas or Network Profiles. Such a procedure can leverage conventional methods such as emails or phone conversations. -API Consumers selects from available Network Profiles and Service Areas offered by the API Provider which then become part of the agreed terms and conditions. +API Consumers selects from available Network Profiles, QoS profiles, and Service Areas offered by the API Provider which then become part of the agreed terms and conditions. This preparation phase is **outside the scope** of the Dedicated Network APIs. @@ -85,7 +88,7 @@ As result of the agreement on the terms and conditions, the following aspects ar - URLs and credentials for the API Consumer to use -- A set of capabilities and performance targets (Network Profiles) that an API Consumer is eligible to use +- A set of capabilities and performance targets (Network Profiles and QoS Profiles) that an API Consumer is eligible to use - A set of geographic areas (Service Areas) that an API Consumer is eligible to use @@ -102,20 +105,28 @@ The diagram below attempts to depict the complete flow including API endpoint, r sequenceDiagram participant App as API Consumer (Application) participant P as Profiles API + participant A as Areas API participant N as Networks API participant A as Accesses API participant Network as Physical Network participant D as Device(s) Note over App,D: Pre-requisites completed - + rect rgba(51, 49, 49, 0.6) note right of App: 1: Reading Profiles App->>P: GET /profiles P->>App: 200 OK (Profiles [profileId, ...]) end + + rect rgba(51, 49, 49, 0.6) + note right of App: 2: Discovering Areas + App->>P: POST /retrieve-service-areas + P->>App: 200 OK (Service areas [areaId, ...]) + end + rect rgba(51, 49, 49, 0.6) - note right of App: 2: Creating a Dedicated Network - App->>N: POST /networks (profileId, serviceArea, serviceTime, ...) + note right of App: 3: Creating a Dedicated Network + App->>N: POST /networks (profileId or qosProfileName, areaId, serviceTime, ...) N->>App: 201 Created (networkId, status=REQUESTED, ...) N <<-->> Network: Provisioning / configuration as needed
Managed by API Provider and Network Provider
Outside scope of the Dedicated Network APIs alt Callback enabled @@ -127,7 +138,7 @@ sequenceDiagram end end rect rgba(51, 49, 49, 0.6) - note right of App: 3: Managing Device Access + note right of App: 4: Managing Device Access loop Create Access resource for a given device to the given network App->>A: POST /accesses (networkId, device) A->>App: 201 Created (accessId) @@ -138,7 +149,7 @@ sequenceDiagram A->>App: 204 No Content end end - Note over App,D: 4: Dedicated Network in ACTIVATED state + Note over App,D: 5: Dedicated Network in ACTIVATED state loop One or more devices D-->>Network: Connect to network Network-->>D: Connection established / denied @@ -146,9 +157,11 @@ sequenceDiagram ``` Description of main steps -1. Reading Profiles: The API Consumer is reading the eligible Network Profiles. Each Network Profile contains properties, like aggregated throughput or QOS profiles. +1. Reading Profiles: The API Consumer is reading the eligible Network Profiles. Each Network Profile contains properties, like aggregated throughput or QoS profiles. Reading of the eligible QoS Profiles may also occur in this step (not shown in the diagram). * The terms and conditions (see [Pre-requisites](#pre-requisites)) may define the conditions, constrains, etc for using the profile. -1. Creating a Dedicated Network: The API Consumer creates a network, providing the profile, service time and service area as input parameters +1. Discovering Areas: The API Consumer is retrieving the eligible Network Service Areas. Each Network Service Area contains properties, like the areas's geographical coordinates and supported network profiles and QoS profiles. + * The terms and conditions (see [Pre-requisites](#pre-requisites)) may define the conditions, constrains, etc for using the service area. +1. Creating a Dedicated Network: The API Consumer creates a network, providing the network profile or QoS profile, service time and service area as input parameters * The network is initially in REQUESTED state. See [network lifecycle](#states-of-the-network) for more information. * The API Consumer can register a sink for receiving network state changes. 1. Managing Device Access: The API Consumer may allow one or more devices to get access to the capabilities and pcapacity of the network @@ -156,7 +169,7 @@ Description of main steps * Creating an Access resource corresponds to giving access for a device to the network. * Deleting an Access resource corresponds to revoking access for a device to the network. 1. When Dedicated Network is in ACTIVATED state: Devices with access will be able to connect to the network. - * When a default QoS profile is defined within the Network Profile (or changed via the Access resources), the all traffic of the device will be treated with this QoS profile as default + * When a single QoS profile is used or a default QoS profile is defined within the Network Profile (or changed via the Access resources), all the traffic of the device will be treated with this QoS profile as default * When multiple QoS profiles are defined within the Network Profile (or changed via the Access resources), the API Consumer may use the QOD API for managing QoS Sessions with the QoS Profiles listed in the Network Profile. ## States of the network