From ff07922ced83eebae96fd0bf5c307baa44d234ac Mon Sep 17 00:00:00 2001 From: FabrizioMoggio <87469955+FabrizioMoggio@users.noreply.github.com> Date: Wed, 26 Jun 2024 12:12:31 +0200 Subject: [PATCH 01/16] TI API Rel 0.9.6: sourceTrafficFilters - removed rel number in "version" field according to:https://github.com/camaraproject/EdgeCloud/issues/272 - sourceTrafficFilters added according to: https://github.com/camaraproject/EdgeCloud/discussions/230#discussioncomment-9879076 - updated link to Identity and Consent: CAMARA-Security-Interoperability: https://github.com/camaraproject/EdgeCloud/issues/277 --- code/API_definitions/Traffic_Influence.yaml | 50 +++++++-------------- 1 file changed, 17 insertions(+), 33 deletions(-) diff --git a/code/API_definitions/Traffic_Influence.yaml b/code/API_definitions/Traffic_Influence.yaml index 50ca111..5474852 100644 --- a/code/API_definitions/Traffic_Influence.yaml +++ b/code/API_definitions/Traffic_Influence.yaml @@ -5,7 +5,7 @@ openapi: 3.0.3 ############################################################################ info: title: Traffic Influence API - version: 0.9.5-wip + version: wip description: | ## Overview The reference scenario foresees a Service, composed by one or more Service @@ -148,13 +148,15 @@ info: traffic toward a specific Application instance.\ \ **sourceTrafficFilters:** - The traffic can be from a specific application port in the Device.\ + The traffic can be from a specific port in the device. If this parameter is + used, the influenced flow is from the port defined in "sourceTrafficFilters" + rathar than the port specified in "Device"\ \ **destinationTrafficFilters:** The Application can expose different service on different interfaces, identified by port and protocol, with this parameter it is possible to - route the traffic just toward some of those services maybe for different - sets of users.\ + route the traffic toward a specific port and protocol exposed by the + Application.\ \ **Device:** An user Device can be provided as an input. The Device can be identified by @@ -166,7 +168,10 @@ info: of each user Device. New "TrafficInfluence" resources are created (with different "trafficInfluenceID"). All the created resources are aggregated by the Application (identified by "appId"). The routing toward the selected - Application instance is only applied for provided user Devices.\ + Application instance is only applied for provided user Devices. "publicPort" + can be used to identify the device. "publicPort" can be also used to + identify the flow to be influenced. If the flow to be influenced is from a + different port, "sourceTrafficFilters" can be used.\ \ **Notification URL and token:** Developers have a chance to specify call back URL on which notifications @@ -175,9 +180,7 @@ info: ## Authentication and Authorization CAMARA guidelines defines a set of authorization flows which can grant API clients access to the API functionality, as outlined in the document - [CAMARA-API-access-and-user-consent.md](https://github.com/camaraproject\ - /IdentityAndConsentManagement/blob/main/documentation/CAMARA-API-access\ - -and-user-consent.md). + [CAMARA-Security-Interoperability.md](https://github.com/camaraproject/IdentityAndConsentManagement/blob/main/documentation/CAMARA-Security-Interoperability.md). Which specific authorization flows are to be used will be determined during onboarding process, happening between the API Client and the Telco Operator exposing the API, taking into account the declared purpose for accessing the @@ -655,15 +658,15 @@ components: - 'deletion in progress' - 'deleted' sourceTrafficFilters: - description: Ports used locally by the device for flows to which - the requested traffic influence should apply. If omitted, then the - traffic influence will apply to all flows between the device and the - specified application server address and ports. + description: Port used locally by the device for flows to which + the requested traffic influence should apply. Traffic influence will + be applied to the flow between "sourcePort" and the Application + Server address and port specified in "destinationTrafficFilters". type: object properties: sourcePort: allOf: - - $ref: "#/components/schemas/PortsSpec" + - $ref: "#/components/schemas/Port" destinationTrafficFilters: description: Identifies the destination IP packet filters. To be used when it is needed a traffic flow towards a specific EAS @@ -673,7 +676,7 @@ components: properties: destinationPort: allOf: - - $ref: "#/components/schemas/PortsSpec" + - $ref: "#/components/schemas/Port" destinationProtocol: allOf: - $ref: "#/components/schemas/Protocol" @@ -811,25 +814,6 @@ components: type: string format: ipv4 example: "84.125.93.10" - PortsSpec: - description: Specification of several TCP or UDP ports - type: object - minProperties: 1 - properties: - ranges: - description: Range of TCP or UDP ports - type: array - minItems: 1 - items: - type: object - required: - - from - - to - properties: - from: - $ref: "#/components/schemas/Port" - to: - $ref: "#/components/schemas/Port" Port: description: TCP or UDP port number type: integer From 2273ea8ce45f58546af5b91e4f5cc4b90cded61a Mon Sep 17 00:00:00 2001 From: FabrizioMoggio <87469955+FabrizioMoggio@users.noreply.github.com> Date: Thu, 27 Jun 2024 12:41:33 +0200 Subject: [PATCH 02/16] Fixed link in the documentation according to: https://github.com/camaraproject/EdgeCloud/issues/277#issuecomment-2194345779 --- code/Test_definitions/Traffic_Influence.yaml | 1030 ++++++++++++++++++ 1 file changed, 1030 insertions(+) create mode 100644 code/Test_definitions/Traffic_Influence.yaml diff --git a/code/Test_definitions/Traffic_Influence.yaml b/code/Test_definitions/Traffic_Influence.yaml new file mode 100644 index 0000000..35d0b31 --- /dev/null +++ b/code/Test_definitions/Traffic_Influence.yaml @@ -0,0 +1,1030 @@ +--- +openapi: 3.0.3 +############################################################################ +# API info # +############################################################################ +info: + title: Traffic Influence API + version: wip + description: | + ## Overview + The reference scenario foresees a Service, composed by one or more Service + Producers deployed in different geographical locations on Edge Cloud Zones + (Edge datacentres of Telco Operator) or in Cloud. The Service Producer, + deployed at the Edge, is referred as Edge Application Server (EAS).\ + An Edge Cloud Zone is a platform in the Telco Operator network, offering + network, compute and storage resources to developers. A developer can + deploy and run applications on an Edge Cloud Zone, meaning reduced latency + to end users that are nearby, as the network path is shorter. A network + operator's EdgeCloud may comprise multiple Edge Cloud Zones, each in a + discrete location to bring latency benefits to end users across a country.\ + The operator can help developers know which of the Edge Cloud Zones will + bring the best performance benefit for a given end user and application\. + The Traffic Influence API (TI API) provides the fastest routing from the + user Device (e.g. a Smartphone) to the optimal EAS instance in a specific + geographical location, installed in an Edge Cloud Zone.\ + If a Service is offered by Cloud Instances and by Edge Instances, the TI API + can be used get the optimal routing of the traffic to the Edge Instances, + maybe for a set of users. Getting the optimal routing can be used to improve + latency maybe in combination with other CAMARA APIs such as QoD (Quality On + Demand). Providing the optimal routing is indeed an important step to get + the optimal latency.\ + If the TI API is used to get the best routing at the Edge for a Device in a + geographical location and the Device moves to another geographical location, + the TI API can be invoked to get the optimal routing in the new geographical + location for that Device. + ## Introduction + The TI API provides the capability to establish the best routing, in terms + of latency, in a specific geographical area, between the user Device, e.g. + the user’s smartphone, and the optimal EAS instance nearby. If the Device + moves in a different geographical location where a more suitable EAS + instance is available, the TI API can be invoked to influence the Device + connectivity to get the optimal routing to the that local instance. It is i + mportant to notice that it is a task of the Application invoking the TI API + to detect the changes in the Device location.\ + The generic architecture for the Service can foresee some Cloud instances of + the Application, one or more Edge Instances of the Application. A component + of the Service is the TI API Consumer. This logical component can be + integrated in other components of the Service to invoke the TI API, creating + a "TrafficInfluence" resource specifying the desired intent.\ + The TI API Producer implements the intent specified in the + "TrafficInfluence" resource.\ + While the TI API can be invoked to activate the fastest routing for any + user, it can also be used to request the best routing for a specific user. + Invoking the TI API for each user, many "TrafficInfluence" resources are + created for each user to provide the requested routing for a set of users.\ + The same approach is used for the geographical locations where the influence + of the traffic must be applied. Invoking the TI API without specifying a + geographical area activates the optimal routing toward any EAS instance, + while invoking the TI API specifying a geographical area activates the + optimal routing only toward the EAS instance located closest to that + geographical area.\ + To activate the optimal routing in selected geographical areas, the TI API + must be invoked for each geographical area.\ + The TI API can be used to: + - optimise the routing when Devices need to consume the service provided + by a local EAS Instances. + - affect an already established Device routing when the Device moves + among different geographical locations. When the TI API consumer detects + a Device has entered a geographical location where an EAS instance is + available, it can invoke the TI API to get the optimal routing toward + that EAS instance. + If the Device moves to another geographical location, served by another + EAS instance, the routing might not be optimal anymore for the new EAS + instance. In the case the Application detects a location change, it can + invoke the TI API again to request a new routing optimization toward + the new EAS instance. + ## Quick Start + The usage of the TI API is based on the management of a "TrafficInfluence" + resource, an object containing the intent requested invoking the TI API and + that is implemented by the platform configuring the Mobile Network for the + optimal routing toward the EAS instance.\ + The "TrafficInfluence" resource can be created (providing the related + parameters that specify the desired intent), queried, modified and + deleted.\ + The TI API is asynchronous, a notification is available providing + information about the status of the requested resource. + For an Application (identified by "appId") many "TrafficInfluence" resources + can be created, e.g. to add multiple users, regions or zones.\ + \ + Before starting to use the TI API, the developer needs to know about the + below specified details:\ + \ + **Base-Url:** + The RESTful TI API endpoint, for example + [**https://tim-api.developer.tim.it/trafficinfluence**](https://tim-api.\ + developer.tim.it/trafficinfluence)\ + \ + **TrafficInfluence:** + This object represents the resource that carries the requirements from the + user to be implemented. The TI API is invoked for the life cycle management + of this resource (CRUD). The resource contains the intents from the TI API + Consumer. Managing this resource, the developer can specify in which + geographical location the routing must be applied, toward which application, + maybe for a specific set of users or for a limited period of time.\ + \ + **trafficInfluenceID:** + Identifier for the Traffic Influence resource. This parameter is returned + by the TI API and must be used to update it (e.g., adding a Device or + deleting it). A different Traffic Influence resource must be created for + any Device or Zone or Region. All these resources are related to an + Application identified by "appId".\ + \ + **apiConsumerId:** + Unique identifier for the TI API Consumer.\ + \ + **region:** + The developer can specify in which geographical area he requires the fastest + routing toward the nearest application instance. A "region" is a wide + geographical area and it contains one or more "zones". A "zone" is where the + Edge Cloud Zone is located. Zones and Regions identifiers are defined and + provided by the Telco Operator and can also be used or retrieved with other + CAMARA APIs (“MEC Exposure & Experience Management API” and “Simple Edge + Discovery”). To add more regions the TI API must be invoked (POST) for each + region. New "TrafficInfluence" resources are created (with different + "trafficInfluenceID"). All the created resources are aggregated by the + Application (identified by "appId").\ + \ + **zone:** + The developer can specify in which geographical area he requires the fastest + routing toward the nearest Application instance. A "zone" is a smaller + geographical area inside a "region". A "zone" is where the Edge Cloud Zone + is located.\ + To add more zones the TI API must be invoked (POST) for each "zone". + New "TrafficInfluence" resources are created (with different + "trafficInfluenceID"). All the created resources are aggregated by the + Application (identified by "appId").\ + \ + **appId:** + A globally unique identifier associated with the application. This + identifier is provided during the application onboarding process. + To influence the traffic toward a specific Application. It is the Operator + Platform that detects the appropriate Application instance in the selected + "region" or "zone".\ + \ + **appInstanceId:** + A globally unique identifier generated by the Operator Platform to identify + a specific instance of the Application on a specific zone. To influence a + traffic toward a specific Application instance.\ + \ + **sourceTrafficFilters:** + The traffic can be from a specific port in the device. If this parameter is + used, the influenced flow is from the port defined in "sourceTrafficFilters" + rathar than the port specified in "Device"\ + \ + **destinationTrafficFilters:** + The Application can expose different service on different interfaces, + identified by port and protocol, with this parameter it is possible to + route the traffic toward a specific port and protocol exposed by the + Application.\ + \ + **Device:** + An user Device can be provided as an input. The Device can be identified by + the phone number (phoneNumber), an external identifier + (networkAccessIdentifier) or by its IP Address (Ipv4Address, Ipv6Address) + also specifying a Port. For IP address both the private (as seen from inside + the Device) and the public (as seen over Internet by a server connected to + the Device) can be used. To add more users the TI API must be invoked (POST) + of each user Device. New "TrafficInfluence" resources are created (with + different "trafficInfluenceID"). All the created resources are aggregated by + the Application (identified by "appId"). The routing toward the selected + Application instance is only applied for provided user Devices. "publicPort" + can be used to identify the device. "publicPort" can be also used to + identify the flow to be influenced. If the flow to be influenced is from a + different port, "sourceTrafficFilters" can be used.\ + \ + **Notification URL and token:** + Developers have a chance to specify call back URL on which notifications + (e.g. session termination) regarding the session can be received from the + service provider. This is also an optional parameter. + ## Authentication and Authorization + CAMARA guidelines defines a set of authorization flows which can grant API + clients access to the API functionality, as outlined in the document + [CAMARA-API-access-and-user-consent.md](https:\ + //github.com/camaraproject/IdentityAndConsentManagement/blob/main/\ + documentation/CAMARA-API-access-and-user-consent.md). + Which specific authorization flows are to be used will be determined during + onboarding process, happening between the API Client and the Telco Operator + exposing the API, taking into account the declared purpose for accessing the + API, while also being subject to the prevailing legal framework dictated by + local legislation.\ + It is important to remark that in cases where personal user 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 3-legged access tokens becomes + mandatory. This measure ensures that the API remains in strict compliance + with user privacy preferences and regulatory obligations, upholding the + principles of transparency and user-centric data control. + ## API Documentation + The TI API is consumed by an Application Function (AF) requesting for the + optimal routing, in term of latency, for the traffic flow from a Device + toward EAS instances in Edge Cloud Zones.\ + When the Application (the EAS) is onboarded and deployed in the Edge Cloud + Zones, the Application is identified with a unique identifier ("appId").\ + Using the application identifier ("appId") and specifying a Zone or a Region + the Telco Operator Platform, autonomously identifies the best instance of + the EAS toward which routing the traffic flow and configures the Mobile + Network accordingly to get the fastest routing.\ + If just the application identifier is used, the Telco Operator Platform + identifies all the EAS Instances and activates the optimal routing on the + Mobile Network.\ + If the optimal routing in term of latency should be available just for a set + of users, the TI API must be invoked for each user creating a new + TrafficInfluce resource for each one. + If the Application offers different services on different interfaces a + traffic filter based on IP, Port and Protocol can be used. I this way it is + also possible to redirect different users to different interfaces. + Here are some possible intents: + 1) activate the optimal routing for any EAS instance: the TI API must be + invoked with the "appId". The Telco Operator Platform identifies all the EAS + instances and activates the optimal routing on the Mobile Network. + 2) activate the optimal routing in a specific Region or Zone: the TI API + must be invoked with the "appId" and the Zones and Regions identifiers. + 3) activate the optimal routing for a user devices: the TI API can be + invoked with a user Device identifier (“Device”). For each user Device, + a TI API invocation is required. + ## Release Notes + The Traffic Influence API reduces the complexity of the 3GPP Traffic + Influence API exposed by the 3GPP Network Exposure Function (NEF) [1]. While + the 3GPP TI API offers fastest routing activation and user mobility among + different edge sites, this version of the CAMARA Traffic Influence API + covers only the fastest routing activation, also for selected users. + User mobility will be introduced in a future version.\ + \ + **Enhancements with respect to the previous release V0.8.1:** + - These release also effects existing data sessions + - These release can be also used to optimize existing data sessions when a + Device moves among geographical areas. + - The ueId parameter is renamed into Device + - The parameter Device, that identifies the User, is now simplified to + guarantee the identification of an existing data session + - InstanceId added + - TrafficFilters description updated + - CAMEL type adopted + - FlowInfo deleted + - OpenAPI version updated to 3.0.3 + - To let the Developer to just work on parameters actually editable, the PUT + method is changed into a PATCH method with a limitation on the + parameters usable and modifiable. A new resource is created, + PatchTrafficInfluence that contains only the editable parameters + The same approach is also adopted for the PUT method and a new resource + PostTrafficInfluence was created with just the editable parameters + - DELETE response code modified as 202. The Deletion request is accepted + (not yet completed, it must be carried on by the system) + - Added response code 400 (bad request) to POST + - General improvement in documentation + - applicationId changed into appId and instanceId changed into appInstanceId + - Alignement of parameters with EdgeCloud_LCM: applicationId changed into + appId and instanceId changed into appInstanceId + - Modified reference to CAMARA Authorization guidelines link + - Telco Edge Site changed in Edge Cloud Zone + - Added: info-contact + - Device: IPV4 and IPV6 changed to represent just one IP. Netmask is no more + valid + - Global tags definition + - Adopted lowerCamelCase for OperationId + - Added descriptions for Delete and Get (for specific resource) methods + - Added missing operationid + - Improvement of callback definition + - Added "description" to the TrafficInfluence resource + - Added "description" to the PatchTrafficInfluence resource + - Added "description" to TrafficInfluenceNotification + - Added "description" to NetworkAccessIdentifier + - Added "description" to ErrResponse + - Added "description" to message + - Added "description" to status + - Added "description" to ErrorInfo + - Removed unused error code SessionNotFound404 + - Alignement of parameters with EdgeCloud_LCM: applicationId changed into + appId and instanceId changed into appInstanceId + - Adoption of OpenId authentication for Consent Management. Client + Credential is removed + - Intruduced xcorrelator + - General alignment with CAMARA on returned Errors + - Modified CAMARA URL to refer to the Edge Cloud Repository + - OAS version now includes "-wip" extension + - simplified "Servers" section and included "vwip" as version + - Updated documentation to better specify how to identify a Device + - Updated the Device parameter according to CAMARA_common.yaml + - change API name in YAML + - introduced sourceTrafficFilters and modified trafficFilters into + destinationTrafficFilters + license: + name: Apache 2.0 + url: https://www.apache.org/licenses/LICENSE-2.0.html + contact: + email: project-email@sample.com + +externalDocs: + description: Product documentation at Camara + url: https://github.com/camaraproject/EdgeCloud +############################################################################ +# Servers # +############################################################################ +servers: + - url: "{apiRoot}/traffic-influence/vwip" + variables: + apiRoot: + default: http://localhost:9091 + description: API root for the Traffic Influence API +############################################################################ +# Tags # +############################################################################ +tags: + - name: Traffic Influence API read + description: Reads existing TrafficInfluence resources + - name: Traffic Influence API write + description: Creates of modifies a TrafficInfluence resource +############################################################################ +# Paths # +############################################################################ +paths: + /traffic-influences: + get: + security: + - openId: + - 'traffic-influence:traffic-influences:read' + parameters: + - $ref: '#/components/parameters/x-correlator' + - in: query + name: appId + schema: + $ref: "#/components/schemas/AppId" + description: Used to select traffic influence resources filtered by + appId + tags: + - Traffic Influence API read + summary: Retries existing TrafficInfluence Resources + description: Reads all of the active TrafficInfluence resources owned by + the same API Consumer + operationId: getTrafficInfluence + responses: + '200': + description: Returns the information about existing TrafficInfluence + resources. + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + type: array + items: + $ref: "#/components/schemas/TrafficInfluence" + "401": + $ref: "#/components/responses/Generic401" + "403": + $ref: "#/components/responses/Generic403" + '500': + $ref: "#/components/responses/GenericError" + "503": + $ref: "#/components/responses/Generic503" + '504': + $ref: "#/components/responses/BackendConnTimeout" + post: + tags: + - Traffic Influence API write + summary: Creates a new TrafficInfluence resource + description: Takes as input an object containing the intents from the API + Consumer and creates a TrafficInfluence resourse accordingly. The + trafficInfluenceID parameter, that is part of the object, must not be + valorized when creating a new resource. For this reason the + trafficInfluenceID parameter must be avoided in the object, anyway it + will be ignored by the API Producer. It is automatically generated by + the system and returned in the response. + operationId: postTrafficInfluence + parameters: + - $ref: '#/components/parameters/x-correlator' + security: + - openId: + - 'traffic-influence:traffic-influences:write' + requestBody: + description: Describes the request body + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/PostTrafficInfluence' + responses: + '201': + description: TrafficInfluence resource created, the related object is + returned with the resource ID (trafficInfluenceID) and status (state) + valorised. + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + Location: + description: Link to the created traffic influence resource + schema: + type: string + description: Link to the created traffic influence resource + content: + application/json: + schema: + $ref: '#/components/schemas/TrafficInfluence' + "400": + $ref: "#/components/responses/Generic400" + '500': + $ref: '#/components/responses/GenericError' + '504': + $ref: '#/components/responses/BackendConnTimeout' + "401": + $ref: "#/components/responses/Generic401" + "403": + $ref: "#/components/responses/Generic403" + "503": + $ref: "#/components/responses/Generic503" + callbacks: + onTrafficInfluenceChanged: + $ref: "#/components/callbacks/onTrafficInfluenceChanged" + /traffic-influences/{trafficInfluenceID}: + parameters: + - name: trafficInfluenceID + in: path + description: Identifier of the specific TrafficInfluence resource to be + retrieved, modified or deleted. It is the value used to fill + trafficInfluenceID parameter. + required: true + schema: + type: string + get: + tags: + - Traffic Influence API read + summary: Reads a specific TrafficInfluence resource identified by the + trafficInfluenceID value. + description: Returns a specific TrafficInfluence resources owned by the + same API Consumer. + operationId: getAllTrafficInfluences + parameters: + - $ref: '#/components/parameters/x-correlator' + security: + - openId: + - 'traffic-influence:traffic-influences:read' + responses: + '200': + description: OK. + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + $ref: '#/components/schemas/TrafficInfluence' + '404': + $ref: '#/components/responses/ResNotFound' + '500': + $ref: '#/components/responses/GenericError' + '504': + $ref: '#/components/responses/BackendConnTimeout' + "401": + $ref: "#/components/responses/Generic401" + "403": + $ref: "#/components/responses/Generic403" + "503": + $ref: "#/components/responses/Generic503" + patch: + tags: + - Traffic Influence API write + summary: updates a specific TrafficInfluence resource, identified by the + trafficInfluenceID value. + description: The resource identified by the trafficInfluenceID value can + be modified. + operationId: patchTrafficInfluence + parameters: + - $ref: '#/components/parameters/x-correlator' + security: + - openId: + - 'traffic-influence:traffic-influences:update' + requestBody: + description: Describes the request body + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/PatchTrafficInfluence' + responses: + '200': + description: TrafficInfluence resource edited, the related object is + returned, the status (state) is updated. + content: + application/json: + schema: + $ref: '#/components/schemas/TrafficInfluence' + headers: + Location: + description: Link to the created traffic influence resource + schema: + type: string + description: Link to the created traffic influence resource + x-correlator: + $ref: '#/components/headers/x-correlator' + "400": + $ref: "#/components/responses/Generic400" + '404': + $ref: '#/components/responses/ResNotFound' + '500': + $ref: '#/components/responses/GenericError' + '504': + $ref: '#/components/responses/BackendConnTimeout' + "401": + $ref: "#/components/responses/Generic401" + "403": + $ref: "#/components/responses/Generic403" + "503": + $ref: "#/components/responses/Generic503" + callbacks: + onTrafficInfluenceChanged: + $ref: "#/components/callbacks/onTrafficInfluenceChanged" + delete: + tags: + - Traffic Influence API write + summary: Delete an existing TrafficInfluence resource + description: invoked by the API Consumer to stop influencing the traffic, + deleting a TrafficInfluence resource previously created. + operationId: deleteTrafficInfluence + security: + - openId: + - 'traffic-influence:traffic-influences:delete' + parameters: + - $ref: '#/components/parameters/x-correlator' + - name: callbackUrl + in: query + required: false + description: | + the location where updated data will be sent. Must be network + accessible + by the source server + schema: + type: string + format: uri + example: https://my-notification-server.com + responses: + '202': + $ref: '#/components/responses/OkDeletionInProgress' + '404': + $ref: '#/components/responses/ResNotFound' + '504': + $ref: '#/components/responses/BackendConnTimeout' + "401": + $ref: "#/components/responses/Generic401" + "403": + $ref: "#/components/responses/Generic403" + "503": + $ref: "#/components/responses/Generic503" + callbacks: + onTrafficInfluenceChanged: + $ref: "#/components/callbacks/onTrafficInfluenceChanged" +############################################################################ +# Components # +############################################################################ +components: + securitySchemes: + openId: + description: to support Consent Management + type: openIdConnect + openIdConnectUrl: https://example.com/.well-known/openid-configuration + + parameters: + x-correlator: + name: x-correlator + in: header + description: Correlation id for the different services. + schema: + type: string + headers: + x-correlator: + description: Correlation id for the different services. + schema: + type: string + ######################################################################### + # Events/Callbacks # + ######################################################################### + callbacks: + onTrafficInfluenceChanged: + # when data is sent, it will be sent to the `callbackUrl` provided + # when making the subscription PLUS the suffix `/event` + '{$request.body.notificationUri}/event': + post: + tags: + - Traffic Influence CALLBACK Operation + summary: Provides a notifican channel for changes in the + TrafficInfluence resource + description: Creating, modifying or delating a Traffic Influece + resourece is an asycronous task. For this reason a notification + channel via callback to a specified URL is provided. + operationId: postTrafficInfluence + parameters: + - $ref: '#/components/parameters/x-correlator' + requestBody: + description: subscription payload which contains the updated + traffic influence instance + content: + application/json: + schema: + $ref: '#/components/schemas/TrafficInfluenceNotification' + responses: + '202': + description: Your server implementation should return this HTTP + status code if the data was received successfully + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + '204': + description: Your server should return this HTTP status code if + no longer interested in further updates + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + ########################################################################## + # Resources # + ########################################################################## + schemas: + TrafficInfluence: + description: Resource conteining the informations to influence the + traffic from the device to the EAS + type: object + properties: + trafficInfluenceID: + type: string + description: Identifier for the Traffic Influence resource. This + parameter is returned by the API and must be used to update it + (e.g., adding new users or deleting it). + apiConsumerId: + type: string + description: Unique Identifier of the TI API Consumer. + appId: + $ref: '#/components/schemas/AppId' + appInstanceId: + $ref: '#/components/schemas/AppInstanceId' + region: + $ref: '#/components/schemas/TypesRegionId' + zone: + $ref: '#/components/schemas/TypesZoneId' + device: + $ref: '#/components/schemas/Device' + state: + type: string + description: it reports the state of the TrafficInfluence resource. + When first invoked, the resource is 'ordered'. When the platforms + prepares the resource, it is 'created'. When the new routing is + enabled in the network, the state is 'active'. If an error occurs + in the resource creation or in its activation, the state is 'error'. + When the DELETE method is invoked the state is + 'deletion in progress'. + After the resource is deleted (as a consequence of the previous + invokation of the DELETE method) the state is 'deleted'. + enum: + - 'ordered' + - 'created' + - 'active' + - 'error' + - 'deletion in progress' + - 'deleted' + sourceTrafficFilters: + description: Port used locally by the device for flows to which + the requested traffic influence should apply. Traffic influence will + be applied to the flow between "sourcePort" and the Application + Server address and port specified in "destinationTrafficFilters". + type: object + properties: + sourcePort: + allOf: + - $ref: "#/components/schemas/Port" + destinationTrafficFilters: + description: Identifies the destination IP packet filters. To be + used when it is needed a traffic flow towards a specific EAS + interface identified by a protocol and a port. Also the Protocol + (e.g. TCP or UDP) can be specified. + type: object + properties: + destinationPort: + allOf: + - $ref: "#/components/schemas/Port" + destinationProtocol: + allOf: + - $ref: "#/components/schemas/Protocol" + notificationUri: + type: string + description: Defines the callback uri which should be notified in + asynchronous way when the state for the requested resources changes + (i.e. ordered to activated) + notificationAuthToken: + type: string + description: Authentification token for callback API + required: + - apiConsumerId + - appId + PatchTrafficInfluence: + description: inherits from TrafficInfluence and restricts the access to + certain parameters. + Only some paramter can be indeed modified with the PATCH operation. + allOf: + - $ref: "#/components/schemas/TrafficInfluence" + properties: + trafficInfluenceID: + readOnly: true + apiConsumerId: + readOnly: true + appId: + readOnly: true + state: + readOnly: true + PostTrafficInfluence: + allOf: + - $ref: "#/components/schemas/TrafficInfluence" + properties: + trafficInfluenceID: + readOnly: true + state: + readOnly: true + TrafficInfluenceNotification: + type: object + description: Notifican channel for changes in the TrafficInfluence + resource + required: + - trafficInfluenceChanged + properties: + trafficInfluenceChanged: + $ref: "#/components/schemas/TrafficInfluence" + ######################################################################## + # Types # + ######################################################################## + TypesZoneId: + description: Unique identifier representing a zone + type: string + additionalProperties: false + TypesRegionId: + description: | + Unique identifier representing a region + type: string + additionalProperties: false + 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` + NOTE: the MNO might support only a subset of these options. The API + invoker can provide multiple identifiers to be compatible across + different MNOs. In this case the identifiers MUST belong to the same + device. + 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 + 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@domain.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 + Protocol: + description: The protocol for the influeced flow. It can be specified and + it is identified by a string according to the column “Keyword” as defined + by IANA (https://www.iana.org/assignments/protocol-numbers/\ + protocol-numbers.xhtml), e.g. UDP or TCP. + type: string + example: "TCP" + 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 + AppInstanceId: + type: string + format: uuid + description: A globally unique identifier associated with a running + instance of an application. OP generates this identifier. + AppId: + type: string + format: uuid + example: "6B29FC40-CA47-1067-B31D-00DD010662DA" + description: A globally unique identifier associated with theapplication. + OP generates this identifier when the application is submitted over NBI. + ######################################################################## + # Responses # + ######################################################################## + ErrResponse: + description: Responce feedback in case of errors + type: object + properties: + status: + description: status for the error + type: string + example: OK + message: + description: additional message for the error + type: string + example: OK + ErrorInfo: + description: Information in case of error + type: object + required: + - code + - message + properties: + code: + type: string + description: Code given to this error + message: + type: string + description: Detailed error description + responses: + ResNotFound: + description: The specified resource was not found + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrResponse' + example: + status: ERROR + message: Resource not found + GenericError: + description: An unknow error has occurred + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrResponse' + example: + status: ERROR + message: Generic error + BackendConnTimeout: + description: Connection timeout towards backend service has occurred + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrResponse' + example: + status: ERROR + message: Backend connection timeout + OkDeletionInProgress: + description: The resource delation request has been accepted + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrResponse' + example: + status: OK + message: Accepted + Generic400: + description: Problem with the client request + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorInfo' + example: + status: 400 + code: INVALID_ARGUMENT + message: Client specified an invalid argument, request body or query + param + Generic401: + description: Authentication problem with the client request + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorInfo' + example: + status: 401 + code: UNAUTHENTICATED + message: Request not authenticated due to missing, invalid, or + expired credentials + Generic403: + description: Client does not have sufficient permission + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorInfo' + examples: + PermissionDenied: + value: + status: 403 + code: PERMISSION_DENIED + message: Client does not have sufficient permissions to perform + this action + InvalidTokenContext: + value: + status: 403 + code: INVALID_TOKEN_CONTEXT + message: Phone number cannot be deducted from access token + context + Generic404: + description: The specified resource was not found + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorInfo' + example: + status: 404 + code: CALL_FORWARDING.UNKNOWN_PHONE_NUMBER + message: Call forwarding check can't be done because the phone + number is unknown. + Generic500: + description: Server error + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorInfo' + example: + status: 500 + code: INTERNAL + message: Server error + Generic503: + description: Service unavailable. Typically the server is down + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorInfo' + example: + status: 503 + code: UNAVAILABLE + message: Service unavailable + Generic504: + description: Request time exceeded. If it happens repeatedly, consider + reducing the request complexity. + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorInfo' + example: + status: 504 + code: TIMEOUT + message: Request timeout exceeded. Try later From cf805239f9f03b80340117d472e75b0a575fc448 Mon Sep 17 00:00:00 2001 From: FabrizioMoggio <87469955+FabrizioMoggio@users.noreply.github.com> Date: Mon, 1 Jul 2024 10:24:16 +0200 Subject: [PATCH 03/16] Delete code/Test_definitions/Traffic_Influence.yaml file uploaded in the wrong folder --- code/Test_definitions/Traffic_Influence.yaml | 1030 ------------------ 1 file changed, 1030 deletions(-) delete mode 100644 code/Test_definitions/Traffic_Influence.yaml diff --git a/code/Test_definitions/Traffic_Influence.yaml b/code/Test_definitions/Traffic_Influence.yaml deleted file mode 100644 index 35d0b31..0000000 --- a/code/Test_definitions/Traffic_Influence.yaml +++ /dev/null @@ -1,1030 +0,0 @@ ---- -openapi: 3.0.3 -############################################################################ -# API info # -############################################################################ -info: - title: Traffic Influence API - version: wip - description: | - ## Overview - The reference scenario foresees a Service, composed by one or more Service - Producers deployed in different geographical locations on Edge Cloud Zones - (Edge datacentres of Telco Operator) or in Cloud. The Service Producer, - deployed at the Edge, is referred as Edge Application Server (EAS).\ - An Edge Cloud Zone is a platform in the Telco Operator network, offering - network, compute and storage resources to developers. A developer can - deploy and run applications on an Edge Cloud Zone, meaning reduced latency - to end users that are nearby, as the network path is shorter. A network - operator's EdgeCloud may comprise multiple Edge Cloud Zones, each in a - discrete location to bring latency benefits to end users across a country.\ - The operator can help developers know which of the Edge Cloud Zones will - bring the best performance benefit for a given end user and application\. - The Traffic Influence API (TI API) provides the fastest routing from the - user Device (e.g. a Smartphone) to the optimal EAS instance in a specific - geographical location, installed in an Edge Cloud Zone.\ - If a Service is offered by Cloud Instances and by Edge Instances, the TI API - can be used get the optimal routing of the traffic to the Edge Instances, - maybe for a set of users. Getting the optimal routing can be used to improve - latency maybe in combination with other CAMARA APIs such as QoD (Quality On - Demand). Providing the optimal routing is indeed an important step to get - the optimal latency.\ - If the TI API is used to get the best routing at the Edge for a Device in a - geographical location and the Device moves to another geographical location, - the TI API can be invoked to get the optimal routing in the new geographical - location for that Device. - ## Introduction - The TI API provides the capability to establish the best routing, in terms - of latency, in a specific geographical area, between the user Device, e.g. - the user’s smartphone, and the optimal EAS instance nearby. If the Device - moves in a different geographical location where a more suitable EAS - instance is available, the TI API can be invoked to influence the Device - connectivity to get the optimal routing to the that local instance. It is i - mportant to notice that it is a task of the Application invoking the TI API - to detect the changes in the Device location.\ - The generic architecture for the Service can foresee some Cloud instances of - the Application, one or more Edge Instances of the Application. A component - of the Service is the TI API Consumer. This logical component can be - integrated in other components of the Service to invoke the TI API, creating - a "TrafficInfluence" resource specifying the desired intent.\ - The TI API Producer implements the intent specified in the - "TrafficInfluence" resource.\ - While the TI API can be invoked to activate the fastest routing for any - user, it can also be used to request the best routing for a specific user. - Invoking the TI API for each user, many "TrafficInfluence" resources are - created for each user to provide the requested routing for a set of users.\ - The same approach is used for the geographical locations where the influence - of the traffic must be applied. Invoking the TI API without specifying a - geographical area activates the optimal routing toward any EAS instance, - while invoking the TI API specifying a geographical area activates the - optimal routing only toward the EAS instance located closest to that - geographical area.\ - To activate the optimal routing in selected geographical areas, the TI API - must be invoked for each geographical area.\ - The TI API can be used to: - - optimise the routing when Devices need to consume the service provided - by a local EAS Instances. - - affect an already established Device routing when the Device moves - among different geographical locations. When the TI API consumer detects - a Device has entered a geographical location where an EAS instance is - available, it can invoke the TI API to get the optimal routing toward - that EAS instance. - If the Device moves to another geographical location, served by another - EAS instance, the routing might not be optimal anymore for the new EAS - instance. In the case the Application detects a location change, it can - invoke the TI API again to request a new routing optimization toward - the new EAS instance. - ## Quick Start - The usage of the TI API is based on the management of a "TrafficInfluence" - resource, an object containing the intent requested invoking the TI API and - that is implemented by the platform configuring the Mobile Network for the - optimal routing toward the EAS instance.\ - The "TrafficInfluence" resource can be created (providing the related - parameters that specify the desired intent), queried, modified and - deleted.\ - The TI API is asynchronous, a notification is available providing - information about the status of the requested resource. - For an Application (identified by "appId") many "TrafficInfluence" resources - can be created, e.g. to add multiple users, regions or zones.\ - \ - Before starting to use the TI API, the developer needs to know about the - below specified details:\ - \ - **Base-Url:** - The RESTful TI API endpoint, for example - [**https://tim-api.developer.tim.it/trafficinfluence**](https://tim-api.\ - developer.tim.it/trafficinfluence)\ - \ - **TrafficInfluence:** - This object represents the resource that carries the requirements from the - user to be implemented. The TI API is invoked for the life cycle management - of this resource (CRUD). The resource contains the intents from the TI API - Consumer. Managing this resource, the developer can specify in which - geographical location the routing must be applied, toward which application, - maybe for a specific set of users or for a limited period of time.\ - \ - **trafficInfluenceID:** - Identifier for the Traffic Influence resource. This parameter is returned - by the TI API and must be used to update it (e.g., adding a Device or - deleting it). A different Traffic Influence resource must be created for - any Device or Zone or Region. All these resources are related to an - Application identified by "appId".\ - \ - **apiConsumerId:** - Unique identifier for the TI API Consumer.\ - \ - **region:** - The developer can specify in which geographical area he requires the fastest - routing toward the nearest application instance. A "region" is a wide - geographical area and it contains one or more "zones". A "zone" is where the - Edge Cloud Zone is located. Zones and Regions identifiers are defined and - provided by the Telco Operator and can also be used or retrieved with other - CAMARA APIs (“MEC Exposure & Experience Management API” and “Simple Edge - Discovery”). To add more regions the TI API must be invoked (POST) for each - region. New "TrafficInfluence" resources are created (with different - "trafficInfluenceID"). All the created resources are aggregated by the - Application (identified by "appId").\ - \ - **zone:** - The developer can specify in which geographical area he requires the fastest - routing toward the nearest Application instance. A "zone" is a smaller - geographical area inside a "region". A "zone" is where the Edge Cloud Zone - is located.\ - To add more zones the TI API must be invoked (POST) for each "zone". - New "TrafficInfluence" resources are created (with different - "trafficInfluenceID"). All the created resources are aggregated by the - Application (identified by "appId").\ - \ - **appId:** - A globally unique identifier associated with the application. This - identifier is provided during the application onboarding process. - To influence the traffic toward a specific Application. It is the Operator - Platform that detects the appropriate Application instance in the selected - "region" or "zone".\ - \ - **appInstanceId:** - A globally unique identifier generated by the Operator Platform to identify - a specific instance of the Application on a specific zone. To influence a - traffic toward a specific Application instance.\ - \ - **sourceTrafficFilters:** - The traffic can be from a specific port in the device. If this parameter is - used, the influenced flow is from the port defined in "sourceTrafficFilters" - rathar than the port specified in "Device"\ - \ - **destinationTrafficFilters:** - The Application can expose different service on different interfaces, - identified by port and protocol, with this parameter it is possible to - route the traffic toward a specific port and protocol exposed by the - Application.\ - \ - **Device:** - An user Device can be provided as an input. The Device can be identified by - the phone number (phoneNumber), an external identifier - (networkAccessIdentifier) or by its IP Address (Ipv4Address, Ipv6Address) - also specifying a Port. For IP address both the private (as seen from inside - the Device) and the public (as seen over Internet by a server connected to - the Device) can be used. To add more users the TI API must be invoked (POST) - of each user Device. New "TrafficInfluence" resources are created (with - different "trafficInfluenceID"). All the created resources are aggregated by - the Application (identified by "appId"). The routing toward the selected - Application instance is only applied for provided user Devices. "publicPort" - can be used to identify the device. "publicPort" can be also used to - identify the flow to be influenced. If the flow to be influenced is from a - different port, "sourceTrafficFilters" can be used.\ - \ - **Notification URL and token:** - Developers have a chance to specify call back URL on which notifications - (e.g. session termination) regarding the session can be received from the - service provider. This is also an optional parameter. - ## Authentication and Authorization - CAMARA guidelines defines a set of authorization flows which can grant API - clients access to the API functionality, as outlined in the document - [CAMARA-API-access-and-user-consent.md](https:\ - //github.com/camaraproject/IdentityAndConsentManagement/blob/main/\ - documentation/CAMARA-API-access-and-user-consent.md). - Which specific authorization flows are to be used will be determined during - onboarding process, happening between the API Client and the Telco Operator - exposing the API, taking into account the declared purpose for accessing the - API, while also being subject to the prevailing legal framework dictated by - local legislation.\ - It is important to remark that in cases where personal user 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 3-legged access tokens becomes - mandatory. This measure ensures that the API remains in strict compliance - with user privacy preferences and regulatory obligations, upholding the - principles of transparency and user-centric data control. - ## API Documentation - The TI API is consumed by an Application Function (AF) requesting for the - optimal routing, in term of latency, for the traffic flow from a Device - toward EAS instances in Edge Cloud Zones.\ - When the Application (the EAS) is onboarded and deployed in the Edge Cloud - Zones, the Application is identified with a unique identifier ("appId").\ - Using the application identifier ("appId") and specifying a Zone or a Region - the Telco Operator Platform, autonomously identifies the best instance of - the EAS toward which routing the traffic flow and configures the Mobile - Network accordingly to get the fastest routing.\ - If just the application identifier is used, the Telco Operator Platform - identifies all the EAS Instances and activates the optimal routing on the - Mobile Network.\ - If the optimal routing in term of latency should be available just for a set - of users, the TI API must be invoked for each user creating a new - TrafficInfluce resource for each one. - If the Application offers different services on different interfaces a - traffic filter based on IP, Port and Protocol can be used. I this way it is - also possible to redirect different users to different interfaces. - Here are some possible intents: - 1) activate the optimal routing for any EAS instance: the TI API must be - invoked with the "appId". The Telco Operator Platform identifies all the EAS - instances and activates the optimal routing on the Mobile Network. - 2) activate the optimal routing in a specific Region or Zone: the TI API - must be invoked with the "appId" and the Zones and Regions identifiers. - 3) activate the optimal routing for a user devices: the TI API can be - invoked with a user Device identifier (“Device”). For each user Device, - a TI API invocation is required. - ## Release Notes - The Traffic Influence API reduces the complexity of the 3GPP Traffic - Influence API exposed by the 3GPP Network Exposure Function (NEF) [1]. While - the 3GPP TI API offers fastest routing activation and user mobility among - different edge sites, this version of the CAMARA Traffic Influence API - covers only the fastest routing activation, also for selected users. - User mobility will be introduced in a future version.\ - \ - **Enhancements with respect to the previous release V0.8.1:** - - These release also effects existing data sessions - - These release can be also used to optimize existing data sessions when a - Device moves among geographical areas. - - The ueId parameter is renamed into Device - - The parameter Device, that identifies the User, is now simplified to - guarantee the identification of an existing data session - - InstanceId added - - TrafficFilters description updated - - CAMEL type adopted - - FlowInfo deleted - - OpenAPI version updated to 3.0.3 - - To let the Developer to just work on parameters actually editable, the PUT - method is changed into a PATCH method with a limitation on the - parameters usable and modifiable. A new resource is created, - PatchTrafficInfluence that contains only the editable parameters - The same approach is also adopted for the PUT method and a new resource - PostTrafficInfluence was created with just the editable parameters - - DELETE response code modified as 202. The Deletion request is accepted - (not yet completed, it must be carried on by the system) - - Added response code 400 (bad request) to POST - - General improvement in documentation - - applicationId changed into appId and instanceId changed into appInstanceId - - Alignement of parameters with EdgeCloud_LCM: applicationId changed into - appId and instanceId changed into appInstanceId - - Modified reference to CAMARA Authorization guidelines link - - Telco Edge Site changed in Edge Cloud Zone - - Added: info-contact - - Device: IPV4 and IPV6 changed to represent just one IP. Netmask is no more - valid - - Global tags definition - - Adopted lowerCamelCase for OperationId - - Added descriptions for Delete and Get (for specific resource) methods - - Added missing operationid - - Improvement of callback definition - - Added "description" to the TrafficInfluence resource - - Added "description" to the PatchTrafficInfluence resource - - Added "description" to TrafficInfluenceNotification - - Added "description" to NetworkAccessIdentifier - - Added "description" to ErrResponse - - Added "description" to message - - Added "description" to status - - Added "description" to ErrorInfo - - Removed unused error code SessionNotFound404 - - Alignement of parameters with EdgeCloud_LCM: applicationId changed into - appId and instanceId changed into appInstanceId - - Adoption of OpenId authentication for Consent Management. Client - Credential is removed - - Intruduced xcorrelator - - General alignment with CAMARA on returned Errors - - Modified CAMARA URL to refer to the Edge Cloud Repository - - OAS version now includes "-wip" extension - - simplified "Servers" section and included "vwip" as version - - Updated documentation to better specify how to identify a Device - - Updated the Device parameter according to CAMARA_common.yaml - - change API name in YAML - - introduced sourceTrafficFilters and modified trafficFilters into - destinationTrafficFilters - license: - name: Apache 2.0 - url: https://www.apache.org/licenses/LICENSE-2.0.html - contact: - email: project-email@sample.com - -externalDocs: - description: Product documentation at Camara - url: https://github.com/camaraproject/EdgeCloud -############################################################################ -# Servers # -############################################################################ -servers: - - url: "{apiRoot}/traffic-influence/vwip" - variables: - apiRoot: - default: http://localhost:9091 - description: API root for the Traffic Influence API -############################################################################ -# Tags # -############################################################################ -tags: - - name: Traffic Influence API read - description: Reads existing TrafficInfluence resources - - name: Traffic Influence API write - description: Creates of modifies a TrafficInfluence resource -############################################################################ -# Paths # -############################################################################ -paths: - /traffic-influences: - get: - security: - - openId: - - 'traffic-influence:traffic-influences:read' - parameters: - - $ref: '#/components/parameters/x-correlator' - - in: query - name: appId - schema: - $ref: "#/components/schemas/AppId" - description: Used to select traffic influence resources filtered by - appId - tags: - - Traffic Influence API read - summary: Retries existing TrafficInfluence Resources - description: Reads all of the active TrafficInfluence resources owned by - the same API Consumer - operationId: getTrafficInfluence - responses: - '200': - description: Returns the information about existing TrafficInfluence - resources. - headers: - x-correlator: - $ref: '#/components/headers/x-correlator' - content: - application/json: - schema: - type: array - items: - $ref: "#/components/schemas/TrafficInfluence" - "401": - $ref: "#/components/responses/Generic401" - "403": - $ref: "#/components/responses/Generic403" - '500': - $ref: "#/components/responses/GenericError" - "503": - $ref: "#/components/responses/Generic503" - '504': - $ref: "#/components/responses/BackendConnTimeout" - post: - tags: - - Traffic Influence API write - summary: Creates a new TrafficInfluence resource - description: Takes as input an object containing the intents from the API - Consumer and creates a TrafficInfluence resourse accordingly. The - trafficInfluenceID parameter, that is part of the object, must not be - valorized when creating a new resource. For this reason the - trafficInfluenceID parameter must be avoided in the object, anyway it - will be ignored by the API Producer. It is automatically generated by - the system and returned in the response. - operationId: postTrafficInfluence - parameters: - - $ref: '#/components/parameters/x-correlator' - security: - - openId: - - 'traffic-influence:traffic-influences:write' - requestBody: - description: Describes the request body - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/PostTrafficInfluence' - responses: - '201': - description: TrafficInfluence resource created, the related object is - returned with the resource ID (trafficInfluenceID) and status (state) - valorised. - headers: - x-correlator: - $ref: '#/components/headers/x-correlator' - Location: - description: Link to the created traffic influence resource - schema: - type: string - description: Link to the created traffic influence resource - content: - application/json: - schema: - $ref: '#/components/schemas/TrafficInfluence' - "400": - $ref: "#/components/responses/Generic400" - '500': - $ref: '#/components/responses/GenericError' - '504': - $ref: '#/components/responses/BackendConnTimeout' - "401": - $ref: "#/components/responses/Generic401" - "403": - $ref: "#/components/responses/Generic403" - "503": - $ref: "#/components/responses/Generic503" - callbacks: - onTrafficInfluenceChanged: - $ref: "#/components/callbacks/onTrafficInfluenceChanged" - /traffic-influences/{trafficInfluenceID}: - parameters: - - name: trafficInfluenceID - in: path - description: Identifier of the specific TrafficInfluence resource to be - retrieved, modified or deleted. It is the value used to fill - trafficInfluenceID parameter. - required: true - schema: - type: string - get: - tags: - - Traffic Influence API read - summary: Reads a specific TrafficInfluence resource identified by the - trafficInfluenceID value. - description: Returns a specific TrafficInfluence resources owned by the - same API Consumer. - operationId: getAllTrafficInfluences - parameters: - - $ref: '#/components/parameters/x-correlator' - security: - - openId: - - 'traffic-influence:traffic-influences:read' - responses: - '200': - description: OK. - headers: - x-correlator: - $ref: '#/components/headers/x-correlator' - content: - application/json: - schema: - $ref: '#/components/schemas/TrafficInfluence' - '404': - $ref: '#/components/responses/ResNotFound' - '500': - $ref: '#/components/responses/GenericError' - '504': - $ref: '#/components/responses/BackendConnTimeout' - "401": - $ref: "#/components/responses/Generic401" - "403": - $ref: "#/components/responses/Generic403" - "503": - $ref: "#/components/responses/Generic503" - patch: - tags: - - Traffic Influence API write - summary: updates a specific TrafficInfluence resource, identified by the - trafficInfluenceID value. - description: The resource identified by the trafficInfluenceID value can - be modified. - operationId: patchTrafficInfluence - parameters: - - $ref: '#/components/parameters/x-correlator' - security: - - openId: - - 'traffic-influence:traffic-influences:update' - requestBody: - description: Describes the request body - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/PatchTrafficInfluence' - responses: - '200': - description: TrafficInfluence resource edited, the related object is - returned, the status (state) is updated. - content: - application/json: - schema: - $ref: '#/components/schemas/TrafficInfluence' - headers: - Location: - description: Link to the created traffic influence resource - schema: - type: string - description: Link to the created traffic influence resource - x-correlator: - $ref: '#/components/headers/x-correlator' - "400": - $ref: "#/components/responses/Generic400" - '404': - $ref: '#/components/responses/ResNotFound' - '500': - $ref: '#/components/responses/GenericError' - '504': - $ref: '#/components/responses/BackendConnTimeout' - "401": - $ref: "#/components/responses/Generic401" - "403": - $ref: "#/components/responses/Generic403" - "503": - $ref: "#/components/responses/Generic503" - callbacks: - onTrafficInfluenceChanged: - $ref: "#/components/callbacks/onTrafficInfluenceChanged" - delete: - tags: - - Traffic Influence API write - summary: Delete an existing TrafficInfluence resource - description: invoked by the API Consumer to stop influencing the traffic, - deleting a TrafficInfluence resource previously created. - operationId: deleteTrafficInfluence - security: - - openId: - - 'traffic-influence:traffic-influences:delete' - parameters: - - $ref: '#/components/parameters/x-correlator' - - name: callbackUrl - in: query - required: false - description: | - the location where updated data will be sent. Must be network - accessible - by the source server - schema: - type: string - format: uri - example: https://my-notification-server.com - responses: - '202': - $ref: '#/components/responses/OkDeletionInProgress' - '404': - $ref: '#/components/responses/ResNotFound' - '504': - $ref: '#/components/responses/BackendConnTimeout' - "401": - $ref: "#/components/responses/Generic401" - "403": - $ref: "#/components/responses/Generic403" - "503": - $ref: "#/components/responses/Generic503" - callbacks: - onTrafficInfluenceChanged: - $ref: "#/components/callbacks/onTrafficInfluenceChanged" -############################################################################ -# Components # -############################################################################ -components: - securitySchemes: - openId: - description: to support Consent Management - type: openIdConnect - openIdConnectUrl: https://example.com/.well-known/openid-configuration - - parameters: - x-correlator: - name: x-correlator - in: header - description: Correlation id for the different services. - schema: - type: string - headers: - x-correlator: - description: Correlation id for the different services. - schema: - type: string - ######################################################################### - # Events/Callbacks # - ######################################################################### - callbacks: - onTrafficInfluenceChanged: - # when data is sent, it will be sent to the `callbackUrl` provided - # when making the subscription PLUS the suffix `/event` - '{$request.body.notificationUri}/event': - post: - tags: - - Traffic Influence CALLBACK Operation - summary: Provides a notifican channel for changes in the - TrafficInfluence resource - description: Creating, modifying or delating a Traffic Influece - resourece is an asycronous task. For this reason a notification - channel via callback to a specified URL is provided. - operationId: postTrafficInfluence - parameters: - - $ref: '#/components/parameters/x-correlator' - requestBody: - description: subscription payload which contains the updated - traffic influence instance - content: - application/json: - schema: - $ref: '#/components/schemas/TrafficInfluenceNotification' - responses: - '202': - description: Your server implementation should return this HTTP - status code if the data was received successfully - headers: - x-correlator: - $ref: '#/components/headers/x-correlator' - '204': - description: Your server should return this HTTP status code if - no longer interested in further updates - headers: - x-correlator: - $ref: '#/components/headers/x-correlator' - ########################################################################## - # Resources # - ########################################################################## - schemas: - TrafficInfluence: - description: Resource conteining the informations to influence the - traffic from the device to the EAS - type: object - properties: - trafficInfluenceID: - type: string - description: Identifier for the Traffic Influence resource. This - parameter is returned by the API and must be used to update it - (e.g., adding new users or deleting it). - apiConsumerId: - type: string - description: Unique Identifier of the TI API Consumer. - appId: - $ref: '#/components/schemas/AppId' - appInstanceId: - $ref: '#/components/schemas/AppInstanceId' - region: - $ref: '#/components/schemas/TypesRegionId' - zone: - $ref: '#/components/schemas/TypesZoneId' - device: - $ref: '#/components/schemas/Device' - state: - type: string - description: it reports the state of the TrafficInfluence resource. - When first invoked, the resource is 'ordered'. When the platforms - prepares the resource, it is 'created'. When the new routing is - enabled in the network, the state is 'active'. If an error occurs - in the resource creation or in its activation, the state is 'error'. - When the DELETE method is invoked the state is - 'deletion in progress'. - After the resource is deleted (as a consequence of the previous - invokation of the DELETE method) the state is 'deleted'. - enum: - - 'ordered' - - 'created' - - 'active' - - 'error' - - 'deletion in progress' - - 'deleted' - sourceTrafficFilters: - description: Port used locally by the device for flows to which - the requested traffic influence should apply. Traffic influence will - be applied to the flow between "sourcePort" and the Application - Server address and port specified in "destinationTrafficFilters". - type: object - properties: - sourcePort: - allOf: - - $ref: "#/components/schemas/Port" - destinationTrafficFilters: - description: Identifies the destination IP packet filters. To be - used when it is needed a traffic flow towards a specific EAS - interface identified by a protocol and a port. Also the Protocol - (e.g. TCP or UDP) can be specified. - type: object - properties: - destinationPort: - allOf: - - $ref: "#/components/schemas/Port" - destinationProtocol: - allOf: - - $ref: "#/components/schemas/Protocol" - notificationUri: - type: string - description: Defines the callback uri which should be notified in - asynchronous way when the state for the requested resources changes - (i.e. ordered to activated) - notificationAuthToken: - type: string - description: Authentification token for callback API - required: - - apiConsumerId - - appId - PatchTrafficInfluence: - description: inherits from TrafficInfluence and restricts the access to - certain parameters. - Only some paramter can be indeed modified with the PATCH operation. - allOf: - - $ref: "#/components/schemas/TrafficInfluence" - properties: - trafficInfluenceID: - readOnly: true - apiConsumerId: - readOnly: true - appId: - readOnly: true - state: - readOnly: true - PostTrafficInfluence: - allOf: - - $ref: "#/components/schemas/TrafficInfluence" - properties: - trafficInfluenceID: - readOnly: true - state: - readOnly: true - TrafficInfluenceNotification: - type: object - description: Notifican channel for changes in the TrafficInfluence - resource - required: - - trafficInfluenceChanged - properties: - trafficInfluenceChanged: - $ref: "#/components/schemas/TrafficInfluence" - ######################################################################## - # Types # - ######################################################################## - TypesZoneId: - description: Unique identifier representing a zone - type: string - additionalProperties: false - TypesRegionId: - description: | - Unique identifier representing a region - type: string - additionalProperties: false - 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` - NOTE: the MNO might support only a subset of these options. The API - invoker can provide multiple identifiers to be compatible across - different MNOs. In this case the identifiers MUST belong to the same - device. - 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 - 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@domain.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 - Protocol: - description: The protocol for the influeced flow. It can be specified and - it is identified by a string according to the column “Keyword” as defined - by IANA (https://www.iana.org/assignments/protocol-numbers/\ - protocol-numbers.xhtml), e.g. UDP or TCP. - type: string - example: "TCP" - 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 - AppInstanceId: - type: string - format: uuid - description: A globally unique identifier associated with a running - instance of an application. OP generates this identifier. - AppId: - type: string - format: uuid - example: "6B29FC40-CA47-1067-B31D-00DD010662DA" - description: A globally unique identifier associated with theapplication. - OP generates this identifier when the application is submitted over NBI. - ######################################################################## - # Responses # - ######################################################################## - ErrResponse: - description: Responce feedback in case of errors - type: object - properties: - status: - description: status for the error - type: string - example: OK - message: - description: additional message for the error - type: string - example: OK - ErrorInfo: - description: Information in case of error - type: object - required: - - code - - message - properties: - code: - type: string - description: Code given to this error - message: - type: string - description: Detailed error description - responses: - ResNotFound: - description: The specified resource was not found - headers: - x-correlator: - $ref: '#/components/headers/x-correlator' - content: - application/json: - schema: - $ref: '#/components/schemas/ErrResponse' - example: - status: ERROR - message: Resource not found - GenericError: - description: An unknow error has occurred - headers: - x-correlator: - $ref: '#/components/headers/x-correlator' - content: - application/json: - schema: - $ref: '#/components/schemas/ErrResponse' - example: - status: ERROR - message: Generic error - BackendConnTimeout: - description: Connection timeout towards backend service has occurred - headers: - x-correlator: - $ref: '#/components/headers/x-correlator' - content: - application/json: - schema: - $ref: '#/components/schemas/ErrResponse' - example: - status: ERROR - message: Backend connection timeout - OkDeletionInProgress: - description: The resource delation request has been accepted - headers: - x-correlator: - $ref: '#/components/headers/x-correlator' - content: - application/json: - schema: - $ref: '#/components/schemas/ErrResponse' - example: - status: OK - message: Accepted - Generic400: - description: Problem with the client request - headers: - x-correlator: - $ref: '#/components/headers/x-correlator' - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorInfo' - example: - status: 400 - code: INVALID_ARGUMENT - message: Client specified an invalid argument, request body or query - param - Generic401: - description: Authentication problem with the client request - headers: - x-correlator: - $ref: '#/components/headers/x-correlator' - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorInfo' - example: - status: 401 - code: UNAUTHENTICATED - message: Request not authenticated due to missing, invalid, or - expired credentials - Generic403: - description: Client does not have sufficient permission - headers: - x-correlator: - $ref: '#/components/headers/x-correlator' - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorInfo' - examples: - PermissionDenied: - value: - status: 403 - code: PERMISSION_DENIED - message: Client does not have sufficient permissions to perform - this action - InvalidTokenContext: - value: - status: 403 - code: INVALID_TOKEN_CONTEXT - message: Phone number cannot be deducted from access token - context - Generic404: - description: The specified resource was not found - headers: - x-correlator: - $ref: '#/components/headers/x-correlator' - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorInfo' - example: - status: 404 - code: CALL_FORWARDING.UNKNOWN_PHONE_NUMBER - message: Call forwarding check can't be done because the phone - number is unknown. - Generic500: - description: Server error - headers: - x-correlator: - $ref: '#/components/headers/x-correlator' - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorInfo' - example: - status: 500 - code: INTERNAL - message: Server error - Generic503: - description: Service unavailable. Typically the server is down - headers: - x-correlator: - $ref: '#/components/headers/x-correlator' - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorInfo' - example: - status: 503 - code: UNAVAILABLE - message: Service unavailable - Generic504: - description: Request time exceeded. If it happens repeatedly, consider - reducing the request complexity. - headers: - x-correlator: - $ref: '#/components/headers/x-correlator' - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorInfo' - example: - status: 504 - code: TIMEOUT - message: Request timeout exceeded. Try later From d0b454be19a52ffe4d59131cd5d359e53009c2a8 Mon Sep 17 00:00:00 2001 From: FabrizioMoggio <87469955+FabrizioMoggio@users.noreply.github.com> Date: Mon, 1 Jul 2024 13:51:56 +0200 Subject: [PATCH 04/16] Add files via upload Addressing most of the comment from here: https://github.com/camaraproject/EdgeCloud/pull/278 Still some contribution is needed to address: - https://github.com/camaraproject/EdgeCloud/pull/278/files/2273ea8ce45f58546af5b91e4f5cc4b90cded61a#r1658269318 - https://github.com/camaraproject/EdgeCloud/pull/278/files/2273ea8ce45f58546af5b91e4f5cc4b90cded61a#r1658270971 --- code/API_definitions/Traffic_Influence.yaml | 109 ++++++++++---------- 1 file changed, 55 insertions(+), 54 deletions(-) diff --git a/code/API_definitions/Traffic_Influence.yaml b/code/API_definitions/Traffic_Influence.yaml index 5474852..d01a3dd 100644 --- a/code/API_definitions/Traffic_Influence.yaml +++ b/code/API_definitions/Traffic_Influence.yaml @@ -19,8 +19,8 @@ info: operator's EdgeCloud may comprise multiple Edge Cloud Zones, each in a discrete location to bring latency benefits to end users across a country.\ The operator can help developers know which of the Edge Cloud Zones will - bring the best performance benefit for a given end user and application\. - The Traffic Influence API (TI API) provides the fastest routing from the + bring the optimal performance for a given end user and application\. + The Traffic Influence API (TI API) provides the optimal routing from the user Device (e.g. a Smartphone) to the optimal EAS instance in a specific geographical location, installed in an Edge Cloud Zone.\ If a Service is offered by Cloud Instances and by Edge Instances, the TI API @@ -34,25 +34,26 @@ info: the TI API can be invoked to get the optimal routing in the new geographical location for that Device. ## Introduction - The TI API provides the capability to establish the best routing, in terms - of latency, in a specific geographical area, between the user Device, e.g. - the user’s smartphone, and the optimal EAS instance nearby. If the Device - moves in a different geographical location where a more suitable EAS + The TI API provides the capability to establish the optimal routing, in + terms of latency, in a specific geographical area, between the user Device, + e.g. the user’s smartphone, and the optimal EAS instance nearby. If the + Device moves in a different geographical location where a more suitable EAS instance is available, the TI API can be invoked to influence the Device - connectivity to get the optimal routing to the that local instance. It is i - mportant to notice that it is a task of the Application invoking the TI API + connectivity to get the optimal routing to the that local instance. It is + important to notice that it is a task of the Application invoking the TI API to detect the changes in the Device location.\ The generic architecture for the Service can foresee some Cloud instances of - the Application, one or more Edge Instances of the Application. A component - of the Service is the TI API Consumer. This logical component can be - integrated in other components of the Service to invoke the TI API, creating - a "TrafficInfluence" resource specifying the desired intent.\ + the Application, one or more Edge Instances of the Application. The TI API + Consumer invokes the TI API creating a "TrafficInfluence" resource + specifying the desired intent.\ The TI API Producer implements the intent specified in the "TrafficInfluence" resource.\ While the TI API can be invoked to activate the fastest routing for any - user, it can also be used to request the best routing for a specific user. - Invoking the TI API for each user, many "TrafficInfluence" resources are - created for each user to provide the requested routing for a set of users.\ + user, it can also be used to request the best routing for a specific user + also specifying,as an option, a source public port and a destination public + port. Invoking the TI API for each user, many "TrafficInfluence" resources + are created for each user to provide the requested routing for a set of + users.\ The same approach is used for the geographical locations where the influence of the traffic must be applied. Invoking the TI API without specifying a geographical area activates the optimal routing toward any EAS instance, @@ -70,10 +71,9 @@ info: available, it can invoke the TI API to get the optimal routing toward that EAS instance. If the Device moves to another geographical location, served by another - EAS instance, the routing might not be optimal anymore for the new EAS - instance. In the case the Application detects a location change, it can - invoke the TI API again to request a new routing optimization toward - the new EAS instance. + EAS instance, the routing might not be optimal anymore. In the case the + Application detects a location change, it can invoke the TI API again to + request a new routing optimization toward the new EAS instance. ## Quick Start The usage of the TI API is based on the management of a "TrafficInfluence" resource, an object containing the intent requested invoking the TI API and @@ -114,26 +114,25 @@ info: Unique identifier for the TI API Consumer.\ \ **region:** - The developer can specify in which geographical area he requires the fastest - routing toward the nearest application instance. A "region" is a wide + The Developer can specify in which geographical area he requires the optimal + routing toward application instances running there. A "region" is a wide geographical area and it contains one or more "zones". A "zone" is where the Edge Cloud Zone is located. Zones and Regions identifiers are defined and provided by the Telco Operator and can also be used or retrieved with other CAMARA APIs (“MEC Exposure & Experience Management API” and “Simple Edge Discovery”). To add more regions the TI API must be invoked (POST) for each - region. New "TrafficInfluence" resources are created (with different - "trafficInfluenceID"). All the created resources are aggregated by the - Application (identified by "appId").\ + region. If in a "region" there are many Application instances active in + different "zones", the TI API can be invoked to configure the optimal routing + for all the instances with just one API call specifying the region. If just + the Application instances in some regions must be affected, the TI API can be + invoked for the regions of interest, without specifying "zone" in the API call. + If just some specific Application instance must be affected, it is not required + to specify any "region" or "zone", the parameter "appInstanceId" can be used.\ \ **zone:** - The developer can specify in which geographical area he requires the fastest - routing toward the nearest Application instance. A "zone" is a smaller - geographical area inside a "region". A "zone" is where the Edge Cloud Zone - is located.\ - To add more zones the TI API must be invoked (POST) for each "zone". - New "TrafficInfluence" resources are created (with different - "trafficInfluenceID"). All the created resources are aggregated by the - Application (identified by "appId").\ + A "zone" is a smaller geographical area inside a "region". A "zone" is where + the Edge Cloud Zone (th data center) is located.\ + To add more zones the TI API must be invoked (POST) for each "zone".\ \ **appId:** A globally unique identifier associated with the application. This @@ -144,13 +143,15 @@ info: \ **appInstanceId:** A globally unique identifier generated by the Operator Platform to identify - a specific instance of the Application on a specific zone. To influence a - traffic toward a specific Application instance.\ + a specific instance of the Application in a specific zone. To influence a + traffic toward a specific Application instance. If just some specific + Application instance must be affected, it is not required to specify any + "region" or "zone", the parameter "appInstanceId" can be used.\ \ **sourceTrafficFilters:** - The traffic can be from a specific port in the device. If this parameter is - used, the influenced flow is from the port defined in "sourceTrafficFilters" - rathar than the port specified in "Device"\ + The traffic can be from a specific public port in the device. If this + parameter is used, the influenced flow is from the public port defined in + "sourceTrafficFilters" rathar than the public port specified in "Device"\ \ **destinationTrafficFilters:** The Application can expose different service on different interfaces, @@ -166,21 +167,22 @@ info: the Device) and the public (as seen over Internet by a server connected to the Device) can be used. To add more users the TI API must be invoked (POST) of each user Device. New "TrafficInfluence" resources are created (with - different "trafficInfluenceID"). All the created resources are aggregated by - the Application (identified by "appId"). The routing toward the selected - Application instance is only applied for provided user Devices. "publicPort" - can be used to identify the device. "publicPort" can be also used to - identify the flow to be influenced. If the flow to be influenced is from a - different port, "sourceTrafficFilters" can be used.\ + different "trafficInfluenceID"). The routing toward the selected Application + instance is only applied for provided user Devices. "publicPort" can be used + to identify the device. "publicPort" can be also used to identify the flow + to be influenced. If the flow to be influenced is from a different public + port, "sourceTrafficFilters" can be used.\ \ **Notification URL and token:** - Developers have a chance to specify call back URL on which notifications - (e.g. session termination) regarding the session can be received from the - service provider. This is also an optional parameter. + Developers can specify a callback URL on which notifications + regarding the requested intent can be received. For example to be notified + when the requested optimal routing is active. ## Authentication and Authorization CAMARA guidelines defines a set of authorization flows which can grant API clients access to the API functionality, as outlined in the document - [CAMARA-Security-Interoperability.md](https://github.com/camaraproject/IdentityAndConsentManagement/blob/main/documentation/CAMARA-Security-Interoperability.md). + [CAMARA-API-access-and-user-consent.md](https:\ + //github.com/camaraproject/IdentityAndConsentManagement/blob/main/\ + documentation/CAMARA-API-access-and-user-consent.md). Which specific authorization flows are to be used will be determined during onboarding process, happening between the API Client and the Telco Operator exposing the API, taking into account the declared purpose for accessing the @@ -221,12 +223,11 @@ info: invoked with a user Device identifier (“Device”). For each user Device, a TI API invocation is required. ## Release Notes - The Traffic Influence API reduces the complexity of the 3GPP Traffic - Influence API exposed by the 3GPP Network Exposure Function (NEF) [1]. While - the 3GPP TI API offers fastest routing activation and user mobility among - different edge sites, this version of the CAMARA Traffic Influence API - covers only the fastest routing activation, also for selected users. - User mobility will be introduced in a future version.\ + The Traffic Influence API reduces the complexity of activating the optimal + routing toward an Application Instance and o provides the optimal routing for + an user moving among geographical areas maybe served by different Application + instances. In this release it is up to the API Consumer to detect the user + moving among geographical areas.\ \ **Enhancements with respect to the previous release V0.8.1:** - These release also effects existing data sessions @@ -658,7 +659,7 @@ components: - 'deletion in progress' - 'deleted' sourceTrafficFilters: - description: Port used locally by the device for flows to which + description: Public source port used by the device for flows to which the requested traffic influence should apply. Traffic influence will be applied to the flow between "sourcePort" and the Application Server address and port specified in "destinationTrafficFilters". From 4910aeabdefdd7aa00b33523078786d940976d23 Mon Sep 17 00:00:00 2001 From: FabrizioMoggio <87469955+FabrizioMoggio@users.noreply.github.com> Date: Mon, 1 Jul 2024 14:26:41 +0200 Subject: [PATCH 05/16] Fix MegaLinter --- code/API_definitions/Traffic_Influence.yaml | 23 +++++++++++---------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/code/API_definitions/Traffic_Influence.yaml b/code/API_definitions/Traffic_Influence.yaml index d01a3dd..076dea4 100644 --- a/code/API_definitions/Traffic_Influence.yaml +++ b/code/API_definitions/Traffic_Influence.yaml @@ -122,12 +122,13 @@ info: CAMARA APIs (“MEC Exposure & Experience Management API” and “Simple Edge Discovery”). To add more regions the TI API must be invoked (POST) for each region. If in a "region" there are many Application instances active in - different "zones", the TI API can be invoked to configure the optimal routing - for all the instances with just one API call specifying the region. If just - the Application instances in some regions must be affected, the TI API can be - invoked for the regions of interest, without specifying "zone" in the API call. - If just some specific Application instance must be affected, it is not required - to specify any "region" or "zone", the parameter "appInstanceId" can be used.\ + different "zones", the TI API can be invoked to configure the optimal + routing for all the instances with just one API call specifying the region. + If just the Application instances in some regions must be affected, the TI + API can be invoked for the regions of interest, without specifying "zone" in + the API call. If just some specific Application instance must be affected, + it is not required to specify any "region" or "zone", the parameter + "appInstanceId" can be used.\ \ **zone:** A "zone" is a smaller geographical area inside a "region". A "zone" is where @@ -144,7 +145,7 @@ info: **appInstanceId:** A globally unique identifier generated by the Operator Platform to identify a specific instance of the Application in a specific zone. To influence a - traffic toward a specific Application instance. If just some specific + traffic toward a specific Application instance. If just some specific Application instance must be affected, it is not required to specify any "region" or "zone", the parameter "appInstanceId" can be used.\ \ @@ -224,10 +225,10 @@ info: a TI API invocation is required. ## Release Notes The Traffic Influence API reduces the complexity of activating the optimal - routing toward an Application Instance and o provides the optimal routing for - an user moving among geographical areas maybe served by different Application - instances. In this release it is up to the API Consumer to detect the user - moving among geographical areas.\ + routing toward an Application Instance and o provides the optimal routing + for an user moving among geographical areas maybe served by different + Application instances. In this release it is up to the API Consumer to + detect the user moving among geographical areas.\ \ **Enhancements with respect to the previous release V0.8.1:** - These release also effects existing data sessions From 9f1704fbe95e5cf291a88db8f20199bebbfd50d8 Mon Sep 17 00:00:00 2001 From: FabrizioMoggio <87469955+FabrizioMoggio@users.noreply.github.com> Date: Mon, 1 Jul 2024 14:30:19 +0200 Subject: [PATCH 06/16] Fix MegaLinter --- code/API_definitions/Traffic_Influence.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/code/API_definitions/Traffic_Influence.yaml b/code/API_definitions/Traffic_Influence.yaml index 076dea4..46cace7 100644 --- a/code/API_definitions/Traffic_Influence.yaml +++ b/code/API_definitions/Traffic_Influence.yaml @@ -122,7 +122,7 @@ info: CAMARA APIs (“MEC Exposure & Experience Management API” and “Simple Edge Discovery”). To add more regions the TI API must be invoked (POST) for each region. If in a "region" there are many Application instances active in - different "zones", the TI API can be invoked to configure the optimal + different "zones", the TI API can be invoked to configure the optimal routing for all the instances with just one API call specifying the region. If just the Application instances in some regions must be affected, the TI API can be invoked for the regions of interest, without specifying "zone" in From ead7ba4ba01247c449555b62a27f3ffdb63f835b Mon Sep 17 00:00:00 2001 From: FabrizioMoggio <87469955+FabrizioMoggio@users.noreply.github.com> Date: Fri, 5 Jul 2024 14:22:43 +0200 Subject: [PATCH 07/16] Update Device with Commonalities Alignment with Device according to: https://github.com/camaraproject/EdgeCloud/discussions/247 --- code/API_definitions/Traffic_Influence.yaml | 57 +++++++++++---------- 1 file changed, 31 insertions(+), 26 deletions(-) diff --git a/code/API_definitions/Traffic_Influence.yaml b/code/API_definitions/Traffic_Influence.yaml index 46cace7..5591239 100644 --- a/code/API_definitions/Traffic_Influence.yaml +++ b/code/API_definitions/Traffic_Influence.yaml @@ -162,8 +162,7 @@ info: \ **Device:** An user Device can be provided as an input. The Device can be identified by - the phone number (phoneNumber), an external identifier - (networkAccessIdentifier) or by its IP Address (Ipv4Address, Ipv6Address) + the phone number (phoneNumber) or by its IP Address (Ipv4Address, Ipv6Address) also specifying a Port. For IP address both the private (as seen from inside the Device) and the public (as seen over Internet by a server connected to the Device) can be used. To add more users the TI API must be invoked (POST) @@ -738,30 +737,36 @@ components: type: string additionalProperties: false 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` - NOTE: the MNO might support only a subset of these options. The API - invoker can provide multiple identifiers to be compatible across - different MNOs. In this case the identifiers MUST belong to the same - device. - 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 + 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 MNO might support only a subset of these options. + The API invoker can provide multiple identifiers to be compatible + across different MNOs. In this case the identifiers MUST belong to + the same device. + NOTE2: for the Commonalities release v0.4, 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 PhoneNumber: description: A public identifier addressing a telephone subscription. In mobile networks it corresponds to the MSISDN (Mobile Station From 3d7c18cd5d8bedfda7233cdca8d237356d2a9649 Mon Sep 17 00:00:00 2001 From: FabrizioMoggio <87469955+FabrizioMoggio@users.noreply.github.com> Date: Fri, 5 Jul 2024 15:03:30 +0200 Subject: [PATCH 08/16] MegaLinter Fix --- code/API_definitions/Traffic_Influence.yaml | 53 +++++++++++---------- 1 file changed, 27 insertions(+), 26 deletions(-) diff --git a/code/API_definitions/Traffic_Influence.yaml b/code/API_definitions/Traffic_Influence.yaml index 5591239..8d57066 100644 --- a/code/API_definitions/Traffic_Influence.yaml +++ b/code/API_definitions/Traffic_Influence.yaml @@ -162,16 +162,17 @@ info: \ **Device:** An user Device can be provided as an input. The Device can be identified by - the phone number (phoneNumber) or by its IP Address (Ipv4Address, Ipv6Address) - also specifying a Port. For IP address both the private (as seen from inside - the Device) and the public (as seen over Internet by a server connected to - the Device) can be used. To add more users the TI API must be invoked (POST) - of each user Device. New "TrafficInfluence" resources are created (with - different "trafficInfluenceID"). The routing toward the selected Application - instance is only applied for provided user Devices. "publicPort" can be used - to identify the device. "publicPort" can be also used to identify the flow - to be influenced. If the flow to be influenced is from a different public - port, "sourceTrafficFilters" can be used.\ + the phone number (phoneNumber) or by its IP Address (Ipv4Address, + Ipv6Address) also specifying a Port. For IP address both the private (as + seen from inside the Device) and the public (as seen over Internet by a + server connected to the Device) can be used. To add more users the TI API + must be invoked (POST) of each user Device. New "TrafficInfluence" + resources are created (with different "trafficInfluenceID"). The routing + toward the selected Application instance is only applied for provided user + Devices. "publicPort" can be used to identify the device. "publicPort" can + be also used to identify the flow to be influenced. If the flow to be + influenced is from a different public port, "sourceTrafficFilters" can be + used.\ \ **Notification URL and token:** Developers can specify a callback URL on which notifications @@ -740,22 +741,22 @@ components: 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 MNO might support only a subset of these options. - The API invoker can provide multiple identifiers to be compatible - across different MNOs. In this case the identifiers MUST belong to - the same device. - NOTE2: for the Commonalities release v0.4, 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. + The developer can choose to provide the below specified device + identifiers: + * `ipv4Address` + * `ipv6Address` + * `phoneNumber` + * `networkAccessIdentifier` + NOTE1: the MNO might support only a subset of these options. + The API invoker can provide multiple identifiers to be compatible + across different MNOs. In this case the identifiers MUST belong to + the same device. + NOTE2: for the Commonalities release v0.4, 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: From f6fe4e1c96d0f71afa1ba9c96198dd60d6d79852 Mon Sep 17 00:00:00 2001 From: FabrizioMoggio <87469955+FabrizioMoggio@users.noreply.github.com> Date: Fri, 5 Jul 2024 15:11:42 +0200 Subject: [PATCH 09/16] MegaLinter Fix it is unfortunate that Common YAML is not compatible with our linter :-( --- code/API_definitions/Traffic_Influence.yaml | 48 ++++++++++----------- 1 file changed, 24 insertions(+), 24 deletions(-) diff --git a/code/API_definitions/Traffic_Influence.yaml b/code/API_definitions/Traffic_Influence.yaml index 8d57066..d0a8b35 100644 --- a/code/API_definitions/Traffic_Influence.yaml +++ b/code/API_definitions/Traffic_Influence.yaml @@ -164,9 +164,9 @@ info: An user Device can be provided as an input. The Device can be identified by the phone number (phoneNumber) or by its IP Address (Ipv4Address, Ipv6Address) also specifying a Port. For IP address both the private (as - seen from inside the Device) and the public (as seen over Internet by a + seen from inside the Device) and the public (as seen over Internet by a server connected to the Device) can be used. To add more users the TI API - must be invoked (POST) of each user Device. New "TrafficInfluence" + must be invoked (POST) of each user Device. New "TrafficInfluence" resources are created (with different "trafficInfluenceID"). The routing toward the selected Application instance is only applied for provided user Devices. "publicPort" can be used to identify the device. "publicPort" can @@ -739,34 +739,34 @@ components: additionalProperties: false 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 MNO might support only a subset of these options. - The API invoker can provide multiple identifiers to be compatible - across different MNOs. In this case the identifiers MUST belong to - the same device. - NOTE2: for the Commonalities release v0.4, 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. + 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 MNO might support only a subset of these options. + The API invoker can provide multiple identifiers to be compatible + across different MNOs. In this case the identifiers MUST belong to + the same device. + NOTE2: for the Commonalities release v0.4, 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" + $ref: "#/components/schemas/PhoneNumber" networkAccessIdentifier: - $ref: "#/components/schemas/NetworkAccessIdentifier" + $ref: "#/components/schemas/NetworkAccessIdentifier" ipv4Address: - $ref: "#/components/schemas/DeviceIpv4Addr" + $ref: "#/components/schemas/DeviceIpv4Addr" ipv6Address: - $ref: "#/components/schemas/DeviceIpv6Address" + $ref: "#/components/schemas/DeviceIpv6Address" minProperties: 1 PhoneNumber: description: A public identifier addressing a telephone subscription. In From ac09c0f926b687d3072aa11028d8da98e75e8d62 Mon Sep 17 00:00:00 2001 From: FabrizioMoggio <87469955+FabrizioMoggio@users.noreply.github.com> Date: Fri, 5 Jul 2024 15:23:38 +0200 Subject: [PATCH 10/16] MegaLinter Fix --- code/API_definitions/Traffic_Influence.yaml | 56 ++++++++++----------- 1 file changed, 28 insertions(+), 28 deletions(-) diff --git a/code/API_definitions/Traffic_Influence.yaml b/code/API_definitions/Traffic_Influence.yaml index d0a8b35..a8dddcd 100644 --- a/code/API_definitions/Traffic_Influence.yaml +++ b/code/API_definitions/Traffic_Influence.yaml @@ -738,36 +738,36 @@ components: type: string additionalProperties: false 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 MNO might support only a subset of these options. - The API invoker can provide multiple identifiers to be compatible - across different MNOs. In this case the identifiers MUST belong to - the same device. - NOTE2: for the Commonalities release v0.4, 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: + 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 MNO might support only a subset of these options. + The API invoker can provide multiple identifiers to be compatible + across different MNOs. In this case the identifiers MUST belong to + the same device. + NOTE2: for the Commonalities release v0.4, 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: + ipv4Address: $ref: "#/components/schemas/DeviceIpv4Addr" - ipv6Address: - $ref: "#/components/schemas/DeviceIpv6Address" - minProperties: 1 + ipv6Address: + $ref: "#/components/schemas/DeviceIpv6Address" + minProperties: 1 PhoneNumber: description: A public identifier addressing a telephone subscription. In mobile networks it corresponds to the MSISDN (Mobile Station From 6b0d3ecd4abfe21b2b4c91e2f8a7e16dfca3bca0 Mon Sep 17 00:00:00 2001 From: FabrizioMoggio <87469955+FabrizioMoggio@users.noreply.github.com> Date: Fri, 5 Jul 2024 15:32:11 +0200 Subject: [PATCH 11/16] MegaLinter Fix --- code/API_definitions/Traffic_Influence.yaml | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/code/API_definitions/Traffic_Influence.yaml b/code/API_definitions/Traffic_Influence.yaml index a8dddcd..e0c0424 100644 --- a/code/API_definitions/Traffic_Influence.yaml +++ b/code/API_definitions/Traffic_Influence.yaml @@ -759,14 +759,14 @@ components: 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" + phoneNumber: + $ref: "#/components/schemas/PhoneNumber" + networkAccessIdentifier: + $ref: "#/components/schemas/NetworkAccessIdentifier" + ipv4Address: + $ref: "#/components/schemas/DeviceIpv4Addr" + ipv6Address: + $ref: "#/components/schemas/DeviceIpv6Address" minProperties: 1 PhoneNumber: description: A public identifier addressing a telephone subscription. In From 607c4529769c88d7218e9c3bf62334f02bd4a730 Mon Sep 17 00:00:00 2001 From: FabrizioMoggio <87469955+FabrizioMoggio@users.noreply.github.com> Date: Mon, 8 Jul 2024 10:09:22 +0200 Subject: [PATCH 12/16] Alignment with Device and EdgeAppMng API - Alignment with Device according to: https://github.com/camaraproject/EdgeCloud/discussions/247 - Alignment with "Edge Application Management API" according to: https://github.com/camaraproject/EdgeCloud/pull/278#discussion_r1666884747 and https://github.com/camaraproject/EdgeCloud/pull/278#discussion_r1666889871 --- code/API_definitions/Traffic_Influence.yaml | 102 +++++++++++--------- 1 file changed, 57 insertions(+), 45 deletions(-) diff --git a/code/API_definitions/Traffic_Influence.yaml b/code/API_definitions/Traffic_Influence.yaml index e0c0424..4186309 100644 --- a/code/API_definitions/Traffic_Influence.yaml +++ b/code/API_definitions/Traffic_Influence.yaml @@ -9,26 +9,31 @@ info: description: | ## Overview The reference scenario foresees a Service, composed by one or more Service - Producers deployed in different geographical locations on Edge Cloud Zones - (Edge datacentres of Telco Operator) or in Cloud. The Service Producer, - deployed at the Edge, is referred as Edge Application Server (EAS).\ - An Edge Cloud Zone is a platform in the Telco Operator network, offering - network, compute and storage resources to developers. A developer can - deploy and run applications on an Edge Cloud Zone, meaning reduced latency - to end users that are nearby, as the network path is shorter. A network - operator's EdgeCloud may comprise multiple Edge Cloud Zones, each in a - discrete location to bring latency benefits to end users across a country.\ + Producers deployed in different geographical locations in a distributed + Telco Edge Cloud. The Service Producer, deployed at the Edge, is referred + as Edge Application Server (EAS).\ + The life cycle management of the EAS can be done with the CAMARA + "Edge Application Management API" whose definition is in the CAMARA Edge + Cloud repository (https://github.com/camaraproject/EdgeCloud). + The Telco Edge Cloud is composed by Edge Cloud Regions that contain + Edge Cloude Zones. For a more complete definition of such Telco Edge Cloud + architecture, please refer to the "Edge Application Management API" + documentation. A developer can deploy and run applications on an Edge + Cloud Zone, meaning reduced latency to end users that are nearby, as the + network path is shorter. A network operator's EdgeCloud may comprise + multiple Edge Cloud Zones, each in a discrete location to bring latency + benefits to end users across a country.\ The operator can help developers know which of the Edge Cloud Zones will bring the optimal performance for a given end user and application\. The Traffic Influence API (TI API) provides the optimal routing from the user Device (e.g. a Smartphone) to the optimal EAS instance in a specific geographical location, installed in an Edge Cloud Zone.\ - If a Service is offered by Cloud Instances and by Edge Instances, the TI API - can be used get the optimal routing of the traffic to the Edge Instances, - maybe for a set of users. Getting the optimal routing can be used to improve - latency maybe in combination with other CAMARA APIs such as QoD (Quality On - Demand). Providing the optimal routing is indeed an important step to get - the optimal latency.\ + If a Service is offered by Cloud Instances and by Edge Instances, the TI + API can be used get the optimal routing of the traffic to the Edge + Instances, maybe for a set of users. Getting the optimal routing can be + used to improve latency maybe in combination with other CAMARA APIs such as + QoD (Quality On Demand). Providing the optimal routing is indeed an + important step to get the optimal latency.\ If the TI API is used to get the best routing at the Edge for a Device in a geographical location and the Device moves to another geographical location, the TI API can be invoked to get the optimal routing in the new geographical @@ -48,9 +53,9 @@ info: specifying the desired intent.\ The TI API Producer implements the intent specified in the "TrafficInfluence" resource.\ - While the TI API can be invoked to activate the fastest routing for any - user, it can also be used to request the best routing for a specific user - also specifying,as an option, a source public port and a destination public + While the TI API can be invoked to activate the optimal routing for any + user, it can also be used to request the optimal routing for a specific user + also specifying, as an option, a source public port and a destination public port. Invoking the TI API for each user, many "TrafficInfluence" resources are created for each user to provide the requested routing for a set of users.\ @@ -113,27 +118,31 @@ info: **apiConsumerId:** Unique identifier for the TI API Consumer.\ \ - **region:** + **edgeCloudRegion:** The Developer can specify in which geographical area he requires the optimal - routing toward application instances running there. A "region" is a wide - geographical area and it contains one or more "zones". A "zone" is where the - Edge Cloud Zone is located. Zones and Regions identifiers are defined and - provided by the Telco Operator and can also be used or retrieved with other - CAMARA APIs (“MEC Exposure & Experience Management API” and “Simple Edge - Discovery”). To add more regions the TI API must be invoked (POST) for each - region. If in a "region" there are many Application instances active in + routing toward application instances running there. An Edge Cloud Region is + equivalent to a Region on a Public Cloud. The higher construct in the + hierarchy exposed to an Application Provider who wishes to deploy an + Application on the Edge Cloud and broadly represents a geography. + An Edge Cloud Region typically contains one or multiple Edge Cloud Zones. + The Edge Cloud Region name is provided by the Telco Operator and can also be + used or retrieved with other CAMARA APIs (e.g. “Edge Application Management + API”). To add more regions the TI API must be invoked (POST) for each + "region". If in a "region" there are many Application instances active in different "zones", the TI API can be invoked to configure the optimal - routing for all the instances with just one API call specifying the region. - If just the Application instances in some regions must be affected, the TI - API can be invoked for the regions of interest, without specifying "zone" in - the API call. If just some specific Application instance must be affected, - it is not required to specify any "region" or "zone", the parameter - "appInstanceId" can be used.\ + routing for all the instances with just one API call specifying the + "region".\ + If just the Application instances in some Edge Cloud Zone must be affected, + the TI API can be invoked for the zones of interest, without specifying + the "region" in the API call. If just some specific Application instance + must be affected, it is not required to specify any "region" or "zone", + and the parameter "appInstanceId" can be used.\ \ - **zone:** - A "zone" is a smaller geographical area inside a "region". A "zone" is where - the Edge Cloud Zone (th data center) is located.\ - To add more zones the TI API must be invoked (POST) for each "zone".\ + **edgeCloudZoneId:** + An Edge Cloud Zone is the lowest level of abstraction exposed to an + Application Provider who wants to deploy an Application on Edge Cloud. + Edge Cloud Zones exists within a Edge Cloud Region.\ + To add more "zones" the TI API must be invoked (POST) for each "zone".\ \ **appId:** A globally unique identifier associated with the application. This @@ -635,10 +644,10 @@ components: $ref: '#/components/schemas/AppId' appInstanceId: $ref: '#/components/schemas/AppInstanceId' - region: - $ref: '#/components/schemas/TypesRegionId' - zone: - $ref: '#/components/schemas/TypesZoneId' + edgeCloudRegion: + $ref: '#/components/schemas/EdgeCloudRegion' + edgeCloudZoneId: + $ref: '#/components/schemas/EdgeCloudZoneId' device: $ref: '#/components/schemas/Device' state: @@ -728,14 +737,17 @@ components: ######################################################################## # Types # ######################################################################## - TypesZoneId: - description: Unique identifier representing a zone + EdgeCloudZoneId: type: string - additionalProperties: false - TypesRegionId: + format: uuid description: | - Unique identifier representing a region + Unique identifier created by the Edge Cloud Platform to identify an + Edge Cloud Zone within an Edge Cloud + EdgeCloudRegion: type: string + description: | + Human readable name of the geographical Edge Cloud Region of + the Edge Cloud. Defined by the Edge Cloud Provider. additionalProperties: false Device: description: | From 479a95b4a313c78e37c7b68252cef7c8fcd2c701 Mon Sep 17 00:00:00 2001 From: FabrizioMoggio <87469955+FabrizioMoggio@users.noreply.github.com> Date: Mon, 8 Jul 2024 10:13:03 +0200 Subject: [PATCH 13/16] MegaLinter Fix --- code/API_definitions/Traffic_Influence.yaml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/code/API_definitions/Traffic_Influence.yaml b/code/API_definitions/Traffic_Influence.yaml index 4186309..7dc8b84 100644 --- a/code/API_definitions/Traffic_Influence.yaml +++ b/code/API_definitions/Traffic_Influence.yaml @@ -30,7 +30,7 @@ info: geographical location, installed in an Edge Cloud Zone.\ If a Service is offered by Cloud Instances and by Edge Instances, the TI API can be used get the optimal routing of the traffic to the Edge - Instances, maybe for a set of users. Getting the optimal routing can be + Instances, maybe for a set of users. Getting the optimal routing can be used to improve latency maybe in combination with other CAMARA APIs such as QoD (Quality On Demand). Providing the optimal routing is indeed an important step to get the optimal latency.\ @@ -139,8 +139,8 @@ info: and the parameter "appInstanceId" can be used.\ \ **edgeCloudZoneId:** - An Edge Cloud Zone is the lowest level of abstraction exposed to an - Application Provider who wants to deploy an Application on Edge Cloud. + An Edge Cloud Zone is the lowest level of abstraction exposed to an + Application Provider who wants to deploy an Application on Edge Cloud. Edge Cloud Zones exists within a Edge Cloud Region.\ To add more "zones" the TI API must be invoked (POST) for each "zone".\ \ From aba0a7d9beb56ef579c0d88bc491a859af235508 Mon Sep 17 00:00:00 2001 From: FabrizioMoggio <87469955+FabrizioMoggio@users.noreply.github.com> Date: Mon, 8 Jul 2024 10:37:28 +0200 Subject: [PATCH 14/16] Updated YAML changelog --- code/API_definitions/Traffic_Influence.yaml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/code/API_definitions/Traffic_Influence.yaml b/code/API_definitions/Traffic_Influence.yaml index 7dc8b84..62ac511 100644 --- a/code/API_definitions/Traffic_Influence.yaml +++ b/code/API_definitions/Traffic_Influence.yaml @@ -297,6 +297,8 @@ info: - change API name in YAML - introduced sourceTrafficFilters and modified trafficFilters into destinationTrafficFilters + - sourceTrafficFilters added + - Alignement with "Edge Application Management API" license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html From ae198c59fdeaadd962213c20bcd3caea7fe96f46 Mon Sep 17 00:00:00 2001 From: FabrizioMoggio <87469955+FabrizioMoggio@users.noreply.github.com> Date: Fri, 2 Aug 2024 10:48:46 +0200 Subject: [PATCH 15/16] documentation improved according the the comments from Deepak --- code/API_definitions/Traffic_Influence.yaml | 50 ++++++++++++++------- 1 file changed, 33 insertions(+), 17 deletions(-) diff --git a/code/API_definitions/Traffic_Influence.yaml b/code/API_definitions/Traffic_Influence.yaml index 62ac511..8ca6642 100644 --- a/code/API_definitions/Traffic_Influence.yaml +++ b/code/API_definitions/Traffic_Influence.yaml @@ -43,10 +43,11 @@ info: terms of latency, in a specific geographical area, between the user Device, e.g. the user’s smartphone, and the optimal EAS instance nearby. If the Device moves in a different geographical location where a more suitable EAS - instance is available, the TI API can be invoked to influence the Device - connectivity to get the optimal routing to the that local instance. It is - important to notice that it is a task of the Application invoking the TI API - to detect the changes in the Device location.\ + instance is available, the TI API can be invoked again to influence the + Device connectivity to get the optimal routing also in the new location. + It is important to notice that it is a task of the TI API Consumer to + detect the changes in the Device location and to invoke the TI API + consequently.\ The generic architecture for the Service can foresee some Cloud instances of the Application, one or more Edge Instances of the Application. The TI API Consumer invokes the TI API creating a "TrafficInfluence" resource @@ -56,17 +57,27 @@ info: While the TI API can be invoked to activate the optimal routing for any user, it can also be used to request the optimal routing for a specific user also specifying, as an option, a source public port and a destination public - port. Invoking the TI API for each user, many "TrafficInfluence" resources - are created for each user to provide the requested routing for a set of - users.\ + port and protocol. Invoking the TI API for each user, many "TrafficInfluence" + resources are created for each user to provide the requested routing for a + set of users. If the TI API is invoked to provide the optimal routing for an + application, for any user in a specific geographical area, for example, and + then the TI API is invoked, for the same application, in the same + geographical area but just for certain users (one API call for each user), + then just the traffic flow those selected users will be optimised.\ The same approach is used for the geographical locations where the influence of the traffic must be applied. Invoking the TI API without specifying a - geographical area activates the optimal routing toward any EAS instance, - while invoking the TI API specifying a geographical area activates the - optimal routing only toward the EAS instance located closest to that - geographical area.\ + geographical area, activates the optimal routing toward the closest EAS + instance. Invoking the TI API specifying a geographical area activates + the optimal routing only if the user is in that geographical area. The flow + is optimised to reach the EAS instance located closest to that geographical + area. In a different geographical area the user will not have the traffic + flow optimised.\ To activate the optimal routing in selected geographical areas, the TI API must be invoked for each geographical area.\ + The API API can also be used to optimise a specific traffic flow identified + by a source port and a destination port and protocol. To optimise the flow + from more source ports or destination ports or protocols, the TI API must be + invoked many times.\ The TI API can be used to: - optimise the routing when Devices need to consume the service provided by a local EAS Instances. @@ -156,7 +167,10 @@ info: a specific instance of the Application in a specific zone. To influence a traffic toward a specific Application instance. If just some specific Application instance must be affected, it is not required to specify any - "region" or "zone", the parameter "appInstanceId" can be used.\ + "region" or "zone", the parameter "appInstanceId" can be used. + The value for appInstanceId can be retrived using the CAMARA API: [Edge + Application Management](https://github.com/camaraproject/EdgeCloud/blob\ + /main/code/API_definitions/Edge-Application-Management.yaml).\ \ **sourceTrafficFilters:** The traffic can be from a specific public port in the device. If this @@ -224,14 +238,16 @@ info: traffic filter based on IP, Port and Protocol can be used. I this way it is also possible to redirect different users to different interfaces. Here are some possible intents: - 1) activate the optimal routing for any EAS instance: the TI API must be - invoked with the "appId". The Telco Operator Platform identifies all the EAS - instances and activates the optimal routing on the Mobile Network. + 1) activate the optimal routing for the closest EAS instance: the TI API + must be invoked with the "appId". The Telco Operator Platform identifies + all the EAS instances and activates the optimal routing on the Mobile + Network so that the user is connect to the closest EAS insteance. 2) activate the optimal routing in a specific Region or Zone: the TI API must be invoked with the "appId" and the Zones and Regions identifiers. - 3) activate the optimal routing for a user devices: the TI API can be + 3) activate the optimal routing for a user Device: the TI API can be invoked with a user Device identifier (“Device”). For each user Device, - a TI API invocation is required. + a TI API invocation is required. The optimal routing is provided only for + the requested Devices. ## Release Notes The Traffic Influence API reduces the complexity of activating the optimal routing toward an Application Instance and o provides the optimal routing From 295d26e5488c379f52234a351aed926d005a75f6 Mon Sep 17 00:00:00 2001 From: FabrizioMoggio <87469955+FabrizioMoggio@users.noreply.github.com> Date: Mon, 5 Aug 2024 11:57:36 +0200 Subject: [PATCH 16/16] MegaLinter Fix --- code/API_definitions/Traffic_Influence.yaml | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/code/API_definitions/Traffic_Influence.yaml b/code/API_definitions/Traffic_Influence.yaml index 8ca6642..e0e3159 100644 --- a/code/API_definitions/Traffic_Influence.yaml +++ b/code/API_definitions/Traffic_Influence.yaml @@ -57,13 +57,14 @@ info: While the TI API can be invoked to activate the optimal routing for any user, it can also be used to request the optimal routing for a specific user also specifying, as an option, a source public port and a destination public - port and protocol. Invoking the TI API for each user, many "TrafficInfluence" - resources are created for each user to provide the requested routing for a - set of users. If the TI API is invoked to provide the optimal routing for an - application, for any user in a specific geographical area, for example, and - then the TI API is invoked, for the same application, in the same - geographical area but just for certain users (one API call for each user), - then just the traffic flow those selected users will be optimised.\ + port and protocol. Invoking the TI API for each user, many + "TrafficInfluence" resources are created for each user to provide the + requested routing for a set of users. If the TI API is invoked to provide + the optimal routing for an application, for any user in a specific + geographical area, for example, and then the TI API is invoked, for the same + application, in the same geographical area but just for certain users (one + API call for each user), then just the traffic flow those selected users + will be optimised.\ The same approach is used for the geographical locations where the influence of the traffic must be applied. Invoking the TI API without specifying a geographical area, activates the optimal routing toward the closest EAS