From 4402266479d4bfd9327b9e62263aa30969eb096e Mon Sep 17 00:00:00 2001 From: FabrizioMoggio <87469955+FabrizioMoggio@users.noreply.github.com> Date: Tue, 16 Apr 2024 11:08:09 +0200 Subject: [PATCH 01/19] test linter --- .../Traffic Influence/Traffic_Influence.yaml | 1642 +++++++++-------- 1 file changed, 904 insertions(+), 738 deletions(-) diff --git a/code/API_definitions/Traffic Influence/Traffic_Influence.yaml b/code/API_definitions/Traffic Influence/Traffic_Influence.yaml index ff70339a..40354f23 100644 --- a/code/API_definitions/Traffic Influence/Traffic_Influence.yaml +++ b/code/API_definitions/Traffic Influence/Traffic_Influence.yaml @@ -1,739 +1,905 @@ -openapi: 3.0.3 -############################################################################ -# API info # -############################################################################ -info: - title: OPAG-CAMARA Traffic Influence API - version: 0.9.3 - 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. - - ## 1. 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 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 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. - - effect 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. - - ## 2. 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. - - **trafficFilters** - The Application can expose different service on different interfaces, with this parameter it is possible to enable just some of those services maybe for different sets of users. - - **Device** - A user Device can be provided as an input. 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. - - **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. - - ## 3. 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. - - ## 4. API Documentation - ## 4.1 Details - - 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. - - 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/ - -############################################################################ -# Servers # -############################################################################ -servers: - - url: "{apiRoot}/{basePath}" - variables: - apiRoot: - default: http://localhost:9091 - description: API root - basePath: - default: ti/v0 - description: Base path 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-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-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-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-influences:write - 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-influences:write - 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: - 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' - trafficFilters: - type: array - items: - type: string - description: Indicates the packet filters of the IP flow. The source IP is not required. It is retrived by the platoform according to the TI API request. If no Traffic Influece resourse is created with a specific Device, any IP will be routed to the Application. If a Traffic Influece resource exists with a specific Device configured, only the related IPs will be routed to the local instance of the Application. The destination IP is not required, it is already known by the platform thanks to the appId and appInstanceId parameters that are used to retive the destination IP. The protocol must 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. The destination port must be specified. - example: TCP 5060 - minItems: 1 - - - minItems: 1 - description: Identifies IP packet filters. To be used when a the Application needs a traffic flow towards a specific EAS interface - 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: - type: object - minProperties: 1 - properties: - phoneNumber: - $ref: "#/components/schemas/PhoneNumber" - networkAccessIdentifier: - $ref: "#/components/schemas/NetworkAccessIdentifier" - ipv4Address: - $ref: "#/components/schemas/Ipv4Address" - ipv6Address: - $ref: "#/components/schemas/Ipv6Address" - description: Device identifier - - NetworkAccessIdentifier: - type: string - example: "123456789@domain.com" - description: identifier for the End User formatted as string, it cab be the user's email address - - PhoneNumber: - type: string - pattern: '^\+?[0-9]{5,15}$' - example: "123456789" - description: Subscriber number in E.164 format (starting with country code). Optionally prefixed with '+'. - - Ipv4Address: - type: string - format: ipv4 - example: "192.168.0.1" - description: IP of the device. A single IPv4 address may be specified in dotted-quad form 1.2.3.4. Only this exact IP number will match the flow control rule. - - - Ipv6Address: - type: string - format: ipv6 - example: "2001:db8:85a3:8d3:1319:8a2e:370:7344" - description: IP of the device. A single IPv6 address, following IETF 5952 format, may be specified like 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 the application. 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 +--- +openapi: 3.0.3 +############################################################################ +# API info # +############################################################################ +info: + title: OPAG-CAMARA Traffic Influence API + version: 0.9.3 + 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. + ## 1. 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. + ## 2. 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.\ + \ + **trafficFilters** + The Application can expose different service on different interfaces, with + this parameter it is possible to enable just some of those services maybe + for different sets of users.\ + \ + **Device** + A user Device can be provided as an input. 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.\ + \ + **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. + ## 3. 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. + ## 4. API Documentation + ## 4.1 Details + 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. + 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/ +############################################################################ +# Servers # +############################################################################ +servers: + - url: "{apiRoot}/{basePath}" + variables: + apiRoot: + default: http://localhost:9091 + description: API root + basePath: + default: ti/v0 + description: Base path 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-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-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-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-influences:write + 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-influences:write + 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: + 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' + trafficFilters: + type: array + items: + type: string + description: Indicates the packet filters of the IP flow. The source + IP is not required. It is retrived by the platoform according to + the TI API request. If no Traffic Influece resourse is created with + a specific Device, any IP will be routed to the Application. If a + Traffic Influece resource exists with a specific Device configured, + only the related IPs will be routed to the local instance of the + Application. The destination IP is not required,it is already known + by the platform thanks to the appId and appInstanceId parameters + that are used to retive the destination IP. The protocol must 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. + The destination port must be specified. + example: TCP 5060 + minItems: 1 + minItems: 1 + description: Identifies IP packet filters. To be used when a the + Application needs a traffic flow towards a specific EAS interface + 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: + type: object + minProperties: 1 + properties: + phoneNumber: + $ref: "#/components/schemas/PhoneNumber" + networkAccessIdentifier: + $ref: "#/components/schemas/NetworkAccessIdentifier" + ipv4Address: + $ref: "#/components/schemas/Ipv4Address" + ipv6Address: + $ref: "#/components/schemas/Ipv6Address" + description: Device identifier + NetworkAccessIdentifier: + type: string + example: "123456789@domain.com" + description: identifier for the End User formatted as string, it cab be + the user's email address. + PhoneNumber: + type: string + pattern: '^\+?[0-9]{5,15}$' + example: "123456789" + description: Subscriber number in E.164 format (starting with country + code). Optionally prefixed with '+'. + Ipv4Address: + type: string + format: ipv4 + example: "192.168.0.1" + description: IP of the device. A single IPv4 address may be specified in + dotted-quad form 1.2.3.4. Only this exact IP number will match the flow + control rule. + Ipv6Address: + type: string + format: ipv6 + example: "2001:db8:85a3:8d3:1319:8a2e:370:7344" + description: IP of the device. A single IPv6 address, following IETF 5952 + format, may be specified like 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 the + application. 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 \ No newline at end of file From 0d5d6a29afb0ee7fc8d70a0fad43ea52c64982f5 Mon Sep 17 00:00:00 2001 From: FabrizioMoggio <87469955+FabrizioMoggio@users.noreply.github.com> Date: Tue, 16 Apr 2024 12:28:10 +0200 Subject: [PATCH 02/19] openid ti: --- .../Traffic Influence/Traffic_Influence.yaml | 1808 ++++++++--------- 1 file changed, 904 insertions(+), 904 deletions(-) diff --git a/code/API_definitions/Traffic Influence/Traffic_Influence.yaml b/code/API_definitions/Traffic Influence/Traffic_Influence.yaml index 40354f23..97757cba 100644 --- a/code/API_definitions/Traffic Influence/Traffic_Influence.yaml +++ b/code/API_definitions/Traffic Influence/Traffic_Influence.yaml @@ -1,905 +1,905 @@ ---- -openapi: 3.0.3 -############################################################################ -# API info # -############################################################################ -info: - title: OPAG-CAMARA Traffic Influence API - version: 0.9.3 - 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. - ## 1. 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. - ## 2. 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.\ - \ - **trafficFilters** - The Application can expose different service on different interfaces, with - this parameter it is possible to enable just some of those services maybe - for different sets of users.\ - \ - **Device** - A user Device can be provided as an input. 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.\ - \ - **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. - ## 3. 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. - ## 4. API Documentation - ## 4.1 Details - 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. - 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/ -############################################################################ -# Servers # -############################################################################ -servers: - - url: "{apiRoot}/{basePath}" - variables: - apiRoot: - default: http://localhost:9091 - description: API root - basePath: - default: ti/v0 - description: Base path 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-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-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-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-influences:write - 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-influences:write - 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: - 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' - trafficFilters: - type: array - items: - type: string - description: Indicates the packet filters of the IP flow. The source - IP is not required. It is retrived by the platoform according to - the TI API request. If no Traffic Influece resourse is created with - a specific Device, any IP will be routed to the Application. If a - Traffic Influece resource exists with a specific Device configured, - only the related IPs will be routed to the local instance of the - Application. The destination IP is not required,it is already known - by the platform thanks to the appId and appInstanceId parameters - that are used to retive the destination IP. The protocol must 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. - The destination port must be specified. - example: TCP 5060 - minItems: 1 - minItems: 1 - description: Identifies IP packet filters. To be used when a the - Application needs a traffic flow towards a specific EAS interface - 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: - type: object - minProperties: 1 - properties: - phoneNumber: - $ref: "#/components/schemas/PhoneNumber" - networkAccessIdentifier: - $ref: "#/components/schemas/NetworkAccessIdentifier" - ipv4Address: - $ref: "#/components/schemas/Ipv4Address" - ipv6Address: - $ref: "#/components/schemas/Ipv6Address" - description: Device identifier - NetworkAccessIdentifier: - type: string - example: "123456789@domain.com" - description: identifier for the End User formatted as string, it cab be - the user's email address. - PhoneNumber: - type: string - pattern: '^\+?[0-9]{5,15}$' - example: "123456789" - description: Subscriber number in E.164 format (starting with country - code). Optionally prefixed with '+'. - Ipv4Address: - type: string - format: ipv4 - example: "192.168.0.1" - description: IP of the device. A single IPv4 address may be specified in - dotted-quad form 1.2.3.4. Only this exact IP number will match the flow - control rule. - Ipv6Address: - type: string - format: ipv6 - example: "2001:db8:85a3:8d3:1319:8a2e:370:7344" - description: IP of the device. A single IPv6 address, following IETF 5952 - format, may be specified like 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 the - application. 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 +--- +openapi: 3.0.3 +############################################################################ +# API info # +############################################################################ +info: + title: OPAG-CAMARA Traffic Influence API + version: 0.9.3 + 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. + ## 1. 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. + ## 2. 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.\ + \ + **trafficFilters** + The Application can expose different service on different interfaces, with + this parameter it is possible to enable just some of those services maybe + for different sets of users.\ + \ + **Device** + A user Device can be provided as an input. 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.\ + \ + **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. + ## 3. 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. + ## 4. API Documentation + ## 4.1 Details + 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. + 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/ +############################################################################ +# Servers # +############################################################################ +servers: + - url: "{apiRoot}/{basePath}" + variables: + apiRoot: + default: http://localhost:9091 + description: API root + basePath: + default: ti/v0 + description: Base path 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: + - ti: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: + - ti: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: + - ti: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: + - ti:traffic-influences:write + 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: + - ti:traffic-influences:write + 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: + 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' + trafficFilters: + type: array + items: + type: string + description: Indicates the packet filters of the IP flow. The source + IP is not required. It is retrived by the platoform according to + the TI API request. If no Traffic Influece resourse is created with + a specific Device, any IP will be routed to the Application. If a + Traffic Influece resource exists with a specific Device configured, + only the related IPs will be routed to the local instance of the + Application. The destination IP is not required,it is already known + by the platform thanks to the appId and appInstanceId parameters + that are used to retive the destination IP. The protocol must 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. + The destination port must be specified. + example: TCP 5060 + minItems: 1 + minItems: 1 + description: Identifies IP packet filters. To be used when a the + Application needs a traffic flow towards a specific EAS interface + 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: + type: object + minProperties: 1 + properties: + phoneNumber: + $ref: "#/components/schemas/PhoneNumber" + networkAccessIdentifier: + $ref: "#/components/schemas/NetworkAccessIdentifier" + ipv4Address: + $ref: "#/components/schemas/Ipv4Address" + ipv6Address: + $ref: "#/components/schemas/Ipv6Address" + description: Device identifier + NetworkAccessIdentifier: + type: string + example: "123456789@domain.com" + description: identifier for the End User formatted as string, it cab be + the user's email address. + PhoneNumber: + type: string + pattern: '^\+?[0-9]{5,15}$' + example: "123456789" + description: Subscriber number in E.164 format (starting with country + code). Optionally prefixed with '+'. + Ipv4Address: + type: string + format: ipv4 + example: "192.168.0.1" + description: IP of the device. A single IPv4 address may be specified in + dotted-quad form 1.2.3.4. Only this exact IP number will match the flow + control rule. + Ipv6Address: + type: string + format: ipv6 + example: "2001:db8:85a3:8d3:1319:8a2e:370:7344" + description: IP of the device. A single IPv6 address, following IETF 5952 + format, may be specified like 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 the + application. 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 \ No newline at end of file From 538851ad1704f4af4aec5aeb411eb7ee52382e1d Mon Sep 17 00:00:00 2001 From: FabrizioMoggio <87469955+FabrizioMoggio@users.noreply.github.com> Date: Tue, 16 Apr 2024 13:28:32 +0200 Subject: [PATCH 03/19] Description --- .../Traffic Influence/Traffic_Influence.yaml | 13 ++++--------- 1 file changed, 4 insertions(+), 9 deletions(-) diff --git a/code/API_definitions/Traffic Influence/Traffic_Influence.yaml b/code/API_definitions/Traffic Influence/Traffic_Influence.yaml index 97757cba..1aadd011 100644 --- a/code/API_definitions/Traffic Influence/Traffic_Influence.yaml +++ b/code/API_definitions/Traffic Influence/Traffic_Influence.yaml @@ -139,7 +139,7 @@ info: 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 + Platform that detects the appropriate Application instance in the selected "region" or "zone".\ \ **appInstanceId** @@ -169,7 +169,7 @@ info: 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). + -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 @@ -259,16 +259,12 @@ paths: tags: - Traffic Influence API read summary: Retries existing TrafficInfluence Resources - description: - > - Reads all of the active TrafficInfluence resources owned by + 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 + description: Returns the information about existing TrafficInfluence resources. headers: x-correlator: @@ -289,7 +285,6 @@ paths: $ref: "#/components/responses/Generic503" '504': $ref: "#/components/responses/BackendConnTimeout" - post: tags: - Traffic Influence API write From f658d99008cb15c4c6818816cdca3bd7d9707f31 Mon Sep 17 00:00:00 2001 From: FabrizioMoggio <87469955+FabrizioMoggio@users.noreply.github.com> Date: Tue, 16 Apr 2024 13:43:49 +0200 Subject: [PATCH 04/19] 2 --- .../Traffic Influence/Traffic_Influence.yaml | 33 +++++++++---------- 1 file changed, 15 insertions(+), 18 deletions(-) diff --git a/code/API_definitions/Traffic Influence/Traffic_Influence.yaml b/code/API_definitions/Traffic Influence/Traffic_Influence.yaml index 1aadd011..09c2de86 100644 --- a/code/API_definitions/Traffic Influence/Traffic_Influence.yaml +++ b/code/API_definitions/Traffic Influence/Traffic_Influence.yaml @@ -249,7 +249,7 @@ paths: - openId: - ti:traffic-influences:read parameters: - - $ref: '#/components/parameters/x-correlator' + - $ref: '#/components/parameters/x-correlator' - in: query name: appId schema: @@ -265,10 +265,10 @@ paths: responses: '200': description: Returns the information about existing TrafficInfluence - resources. + resources. headers: x-correlator: - $ref: '#/components/headers/x-correlator' + $ref: '#/components/headers/x-correlator' content: application/json: schema: @@ -298,7 +298,7 @@ paths: the system and returned in the response. operationId: postTrafficInfluence parameters: - - $ref: '#/components/parameters/x-correlator' + - $ref: '#/components/parameters/x-correlator' security: - openId: - ti:traffic-influences:write @@ -313,7 +313,7 @@ paths: '201': description: TrafficInfluence resource created, the related object is returned with the resource ID (trafficInfluenceID) and status (state) - valorised. + valorised. headers: x-correlator: $ref: '#/components/headers/x-correlator' @@ -327,7 +327,7 @@ paths: schema: $ref: '#/components/schemas/TrafficInfluence' "400": - $ref: "#/components/responses/Generic400" + $ref: "#/components/responses/Generic400" '500': $ref: '#/components/responses/GenericError' '504': @@ -351,7 +351,6 @@ paths: required: true schema: type: string - get: tags: - Traffic Influence API read @@ -361,16 +360,16 @@ paths: same API Consumer. operationId: getAllTrafficInfluences parameters: - - $ref: '#/components/parameters/x-correlator' + - $ref: '#/components/parameters/x-correlator' security: - openId: - ti:traffic-influences:read responses: '200': - description: OK. + description: OK. headers: x-correlator: - $ref: '#/components/headers/x-correlator' + $ref: '#/components/headers/x-correlator' content: application/json: schema: @@ -396,7 +395,7 @@ paths: be modified. operationId: patchTrafficInfluence parameters: - - $ref: '#/components/parameters/x-correlator' + - $ref: '#/components/parameters/x-correlator' security: - openId: - ti:traffic-influences:write @@ -410,7 +409,7 @@ paths: responses: '200': description: TrafficInfluence resource edited, the related object is - returned, the status (state) is updated. + returned, the status (state) is updated. content: application/json: schema: @@ -422,9 +421,9 @@ paths: type: string description: Link to the created traffic influence resource x-correlator: - $ref: '#/components/headers/x-correlator' + $ref: '#/components/headers/x-correlator' "400": - $ref: "#/components/responses/Generic400" + $ref: "#/components/responses/Generic400" '404': $ref: '#/components/responses/ResNotFound' '500': @@ -446,12 +445,12 @@ paths: 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 + operationId: deleteTrafficInfluence security: - openId: - ti:traffic-influences:write parameters: - - $ref: '#/components/parameters/x-correlator' + - $ref: '#/components/parameters/x-correlator' - name: callbackUrl in: query required: false @@ -495,7 +494,6 @@ components: description: Correlation id for the different services. schema: type: string - headers: x-correlator: description: Correlation id for the different services. @@ -807,7 +805,6 @@ components: code: INVALID_ARGUMENT message: Client specified an invalid argument, request body or query param - Generic401: description: Authentication problem with the client request headers: From 9316ab66c65a6e061d97502f6cda2c3a3fe2d6ee Mon Sep 17 00:00:00 2001 From: FabrizioMoggio <87469955+FabrizioMoggio@users.noreply.github.com> Date: Tue, 16 Apr 2024 13:54:51 +0200 Subject: [PATCH 05/19] blanks --- .../Traffic Influence/Traffic_Influence.yaml | 34 +++++++++---------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/code/API_definitions/Traffic Influence/Traffic_Influence.yaml b/code/API_definitions/Traffic Influence/Traffic_Influence.yaml index 09c2de86..e58a2f90 100644 --- a/code/API_definitions/Traffic Influence/Traffic_Influence.yaml +++ b/code/API_definitions/Traffic Influence/Traffic_Influence.yaml @@ -360,7 +360,7 @@ paths: same API Consumer. operationId: getAllTrafficInfluences parameters: - - $ref: '#/components/parameters/x-correlator' + - $ref: '#/components/parameters/x-correlator' security: - openId: - ti:traffic-influences:read @@ -369,7 +369,7 @@ paths: description: OK. headers: x-correlator: - $ref: '#/components/headers/x-correlator' + $ref: '#/components/headers/x-correlator' content: application/json: schema: @@ -421,7 +421,7 @@ paths: type: string description: Link to the created traffic influence resource x-correlator: - $ref: '#/components/headers/x-correlator' + $ref: '#/components/headers/x-correlator' "400": $ref: "#/components/responses/Generic400" '404': @@ -517,7 +517,7 @@ components: channel via callback to a specified URL is provided. operationId: postTrafficInfluence parameters: - - $ref: '#/components/parameters/x-correlator' + - $ref: '#/components/parameters/x-correlator' requestBody: description: subscription payload which contains the updated traffic influence instance @@ -528,12 +528,12 @@ components: responses: '202': description: | - Your server implementation should return this HTTP + Your server implementation should return this HTTP status code if the data was received successfully headers: x-correlator: - $ref: '#/components/headers/x-correlator' + $ref: '#/components/headers/x-correlator' '204': description: | Your server should return this HTTP status code if no @@ -654,17 +654,17 @@ components: $ref: "#/components/schemas/TrafficInfluence" ####################################################### # TYPES -####################################################### +####################################################### TypesZoneId: description: | Unique identifier representing a zone type: string - additionalProperties: false + additionalProperties: false TypesRegionId: description: | Unique identifier representing a region type: string - additionalProperties: false + additionalProperties: false Device: type: object minProperties: 1 @@ -713,8 +713,8 @@ components: example: "6B29FC40-CA47-1067-B31D-00DD010662DA" description: A globally unique identifier associated with the application. OP generates this identifier when the application is - submitted over NBI. -###################################################### + submitted over NBI. +####################################################### # RESPONSES ####################################################### ErrResponse: @@ -730,7 +730,7 @@ components: type: string example: OK ErrorInfo: - description: Information in case of error + description: Information in case of error type: object required: - code @@ -747,7 +747,7 @@ components: description: The specified resource was not found headers: x-correlator: - $ref: '#/components/headers/x-correlator' + $ref: '#/components/headers/x-correlator' content: application/json: schema: @@ -759,7 +759,7 @@ components: description: An unknow error has occurred headers: x-correlator: - $ref: '#/components/headers/x-correlator' + $ref: '#/components/headers/x-correlator' content: application/json: schema: @@ -771,7 +771,7 @@ components: description: Connection timeout towards backend service has occurred headers: x-correlator: - $ref: '#/components/headers/x-correlator' + $ref: '#/components/headers/x-correlator' content: application/json: schema: @@ -783,11 +783,11 @@ components: description: The resource delation request has been accepted headers: x-correlator: - $ref: '#/components/headers/x-correlator' + $ref: '#/components/headers/x-correlator' content: application/json: schema: - $ref: '#/components/schemas/ErrResponse' + $ref: '#/components/schemas/ErrResponse' example: status: OK message: Accepted From a80bdabb6df7da4db0b16eb94879d9fc612bcd41 Mon Sep 17 00:00:00 2001 From: FabrizioMoggio <87469955+FabrizioMoggio@users.noreply.github.com> Date: Tue, 16 Apr 2024 14:07:42 +0200 Subject: [PATCH 06/19] callback --- .../Traffic Influence/Traffic_Influence.yaml | 86 +++++++++---------- 1 file changed, 43 insertions(+), 43 deletions(-) diff --git a/code/API_definitions/Traffic Influence/Traffic_Influence.yaml b/code/API_definitions/Traffic Influence/Traffic_Influence.yaml index e58a2f90..1f1b2d0a 100644 --- a/code/API_definitions/Traffic Influence/Traffic_Influence.yaml +++ b/code/API_definitions/Traffic Influence/Traffic_Influence.yaml @@ -369,7 +369,7 @@ paths: description: OK. headers: x-correlator: - $ref: '#/components/headers/x-correlator' + $ref: '#/components/headers/x-correlator' content: application/json: schema: @@ -421,7 +421,7 @@ paths: type: string description: Link to the created traffic influence resource x-correlator: - $ref: '#/components/headers/x-correlator' + $ref: '#/components/headers/x-correlator' "400": $ref: "#/components/responses/Generic400" '404': @@ -504,44 +504,44 @@ components: ####################################################### 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' + # 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 ####################################################### @@ -716,7 +716,7 @@ components: submitted over NBI. ####################################################### # RESPONSES -####################################################### +####################################################### ErrResponse: description: Responce feedback in case of errors type: object @@ -747,7 +747,7 @@ components: description: The specified resource was not found headers: x-correlator: - $ref: '#/components/headers/x-correlator' + $ref: '#/components/headers/x-correlator' content: application/json: schema: @@ -787,7 +787,7 @@ components: content: application/json: schema: - $ref: '#/components/schemas/ErrResponse' + $ref: '#/components/schemas/ErrResponse' example: status: OK message: Accepted From d50d5fd0c64cd15308a15cf4c6c6e47e7d89d8cb Mon Sep 17 00:00:00 2001 From: FabrizioMoggio <87469955+FabrizioMoggio@users.noreply.github.com> Date: Tue, 16 Apr 2024 14:17:35 +0200 Subject: [PATCH 07/19] fix --- .../Traffic Influence/Traffic_Influence.yaml | 57 +++++++++---------- 1 file changed, 26 insertions(+), 31 deletions(-) diff --git a/code/API_definitions/Traffic Influence/Traffic_Influence.yaml b/code/API_definitions/Traffic Influence/Traffic_Influence.yaml index 1f1b2d0a..771eff2c 100644 --- a/code/API_definitions/Traffic Influence/Traffic_Influence.yaml +++ b/code/API_definitions/Traffic Influence/Traffic_Influence.yaml @@ -517,7 +517,7 @@ components: channel via callback to a specified URL is provided. operationId: postTrafficInfluence parameters: - - $ref: '#/components/parameters/x-correlator' + - $ref: '#/components/parameters/x-correlator' requestBody: description: subscription payload which contains the updated traffic influence instance @@ -526,22 +526,18 @@ components: 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' + '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 ####################################################### @@ -557,16 +553,16 @@ components: 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. + type: string + description: Unique Identifier of the TI API Consumer. appId: - $ref: '#/components/schemas/AppId' + $ref: '#/components/schemas/AppId' appInstanceId: - $ref: '#/components/schemas/AppInstanceId' + $ref: '#/components/schemas/AppInstanceId' region: - $ref: '#/components/schemas/TypesRegionId' + $ref: '#/components/schemas/TypesRegionId' zone: - $ref: '#/components/schemas/TypesZoneId' + $ref: '#/components/schemas/TypesZoneId' device: $ref: '#/components/schemas/Device' state: @@ -610,13 +606,13 @@ components: description: Identifies IP packet filters. To be used when a the Application needs a traffic flow towards a specific EAS interface 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) + 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 + type: string + description: Authentification token for callback API required: - apiConsumerId - appId @@ -656,8 +652,7 @@ components: # TYPES ####################################################### TypesZoneId: - description: | - Unique identifier representing a zone + description: Unique identifier representing a zone type: string additionalProperties: false TypesRegionId: From 8b9a79f8b803e689cc3866c6ce100cb21075dadc Mon Sep 17 00:00:00 2001 From: FabrizioMoggio <87469955+FabrizioMoggio@users.noreply.github.com> Date: Tue, 16 Apr 2024 14:23:53 +0200 Subject: [PATCH 08/19] Add files via upload From 05c56bef0c693e08236eabf6b471b2226af07a90 Mon Sep 17 00:00:00 2001 From: FabrizioMoggio <87469955+FabrizioMoggio@users.noreply.github.com> Date: Tue, 16 Apr 2024 14:35:17 +0200 Subject: [PATCH 09/19] comm --- .../Traffic Influence/Traffic_Influence.yaml | 30 +++++++++---------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/code/API_definitions/Traffic Influence/Traffic_Influence.yaml b/code/API_definitions/Traffic Influence/Traffic_Influence.yaml index 771eff2c..ff0bb4fa 100644 --- a/code/API_definitions/Traffic Influence/Traffic_Influence.yaml +++ b/code/API_definitions/Traffic Influence/Traffic_Influence.yaml @@ -478,9 +478,9 @@ paths: callbacks: onTrafficInfluenceChanged: $ref: "#/components/callbacks/onTrafficInfluenceChanged" -####################################################### -# COMPONENTS -####################################################### +################################################################################# +# Components # +################################################################################# components: securitySchemes: openId: @@ -499,9 +499,9 @@ components: description: Correlation id for the different services. schema: type: string -####################################################### -# EVENTS/CALLBACKS -####################################################### +################################################################################# +# Events/Callbacks # +################################################################################# callbacks: onTrafficInfluenceChanged: # when data is sent, it will be sent to the `callbackUrl` provided @@ -538,9 +538,9 @@ components: headers: x-correlator: $ref: '#/components/headers/x-correlator' -####################################################### -# RESOURCES -####################################################### +################################################################################# +# Resources # +################################################################################# schemas: TrafficInfluence: description: Resource conteining the informations to influence the @@ -648,9 +648,9 @@ components: properties: trafficInfluenceChanged: $ref: "#/components/schemas/TrafficInfluence" -####################################################### -# TYPES -####################################################### +################################################################################# +# Types # +################################################################################# TypesZoneId: description: Unique identifier representing a zone type: string @@ -709,9 +709,9 @@ components: description: A globally unique identifier associated with the application. OP generates this identifier when the application is submitted over NBI. -####################################################### -# RESPONSES -####################################################### +################################################################################# +# Responses # +################################################################################# ErrResponse: description: Responce feedback in case of errors type: object From 4d658c690a9405e25f57f683160ce9e8a69ade0d Mon Sep 17 00:00:00 2001 From: FabrizioMoggio <87469955+FabrizioMoggio@users.noreply.github.com> Date: Tue, 16 Apr 2024 14:48:00 +0200 Subject: [PATCH 10/19] ## --- .../Traffic Influence/Traffic_Influence.yaml | 30 +++++++++---------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/code/API_definitions/Traffic Influence/Traffic_Influence.yaml b/code/API_definitions/Traffic Influence/Traffic_Influence.yaml index ff0bb4fa..8638cabf 100644 --- a/code/API_definitions/Traffic Influence/Traffic_Influence.yaml +++ b/code/API_definitions/Traffic Influence/Traffic_Influence.yaml @@ -478,9 +478,9 @@ paths: callbacks: onTrafficInfluenceChanged: $ref: "#/components/callbacks/onTrafficInfluenceChanged" -################################################################################# -# Components # -################################################################################# +############################################################################ +# Components # +############################################################################ components: securitySchemes: openId: @@ -499,9 +499,9 @@ components: description: Correlation id for the different services. schema: type: string -################################################################################# -# Events/Callbacks # -################################################################################# +############################################################################ +# Events/Callbacks # +############################################################################ callbacks: onTrafficInfluenceChanged: # when data is sent, it will be sent to the `callbackUrl` provided @@ -538,9 +538,9 @@ components: headers: x-correlator: $ref: '#/components/headers/x-correlator' -################################################################################# -# Resources # -################################################################################# +############################################################################ +# Resources # +############################################################################ schemas: TrafficInfluence: description: Resource conteining the informations to influence the @@ -648,9 +648,9 @@ components: properties: trafficInfluenceChanged: $ref: "#/components/schemas/TrafficInfluence" -################################################################################# -# Types # -################################################################################# +############################################################################ +# Types # +############################################################################ TypesZoneId: description: Unique identifier representing a zone type: string @@ -709,9 +709,9 @@ components: description: A globally unique identifier associated with the application. OP generates this identifier when the application is submitted over NBI. -################################################################################# -# Responses # -################################################################################# +############################################################################ +# Responses # +############################################################################ ErrResponse: description: Responce feedback in case of errors type: object From e18942a78b4fbd3f35afab5b904a1819d9d270ad Mon Sep 17 00:00:00 2001 From: FabrizioMoggio <87469955+FabrizioMoggio@users.noreply.github.com> Date: Tue, 16 Apr 2024 14:56:05 +0200 Subject: [PATCH 11/19] Add files via upload --- code/API_definitions/Traffic Influence/Traffic_Influence.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/code/API_definitions/Traffic Influence/Traffic_Influence.yaml b/code/API_definitions/Traffic Influence/Traffic_Influence.yaml index 8638cabf..4e891c61 100644 --- a/code/API_definitions/Traffic Influence/Traffic_Influence.yaml +++ b/code/API_definitions/Traffic Influence/Traffic_Influence.yaml @@ -648,7 +648,7 @@ components: properties: trafficInfluenceChanged: $ref: "#/components/schemas/TrafficInfluence" -############################################################################ +############################################################################ # Types # ############################################################################ TypesZoneId: @@ -709,7 +709,7 @@ components: description: A globally unique identifier associated with the application. OP generates this identifier when the application is submitted over NBI. -############################################################################ +############################################################################ # Responses # ############################################################################ ErrResponse: From 37b4fa3b125036084a8645cae30e70d8ba0157fb Mon Sep 17 00:00:00 2001 From: FabrizioMoggio <87469955+FabrizioMoggio@users.noreply.github.com> Date: Tue, 16 Apr 2024 15:36:15 +0200 Subject: [PATCH 12/19] Add files via upload --- .../Traffic Influence/Traffic_Influence.yaml | 24 +++++++++---------- 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/code/API_definitions/Traffic Influence/Traffic_Influence.yaml b/code/API_definitions/Traffic Influence/Traffic_Influence.yaml index 4e891c61..14065ec4 100644 --- a/code/API_definitions/Traffic Influence/Traffic_Influence.yaml +++ b/code/API_definitions/Traffic Influence/Traffic_Influence.yaml @@ -499,9 +499,9 @@ components: description: Correlation id for the different services. schema: type: string -############################################################################ -# Events/Callbacks # -############################################################################ + ######################################################################### + # Events/Callbacks # + ######################################################################### callbacks: onTrafficInfluenceChanged: # when data is sent, it will be sent to the `callbackUrl` provided @@ -538,9 +538,9 @@ components: headers: x-correlator: $ref: '#/components/headers/x-correlator' -############################################################################ -# Resources # -############################################################################ + ########################################################################## + # Resources # + ########################################################################## schemas: TrafficInfluence: description: Resource conteining the informations to influence the @@ -648,9 +648,9 @@ components: properties: trafficInfluenceChanged: $ref: "#/components/schemas/TrafficInfluence" -############################################################################ -# Types # -############################################################################ + ######################################################################## + # Types # + ######################################################################## TypesZoneId: description: Unique identifier representing a zone type: string @@ -709,9 +709,9 @@ components: description: A globally unique identifier associated with the application. OP generates this identifier when the application is submitted over NBI. -############################################################################ -# Responses # -############################################################################ + ######################################################################## + # Responses # + ######################################################################## ErrResponse: description: Responce feedback in case of errors type: object From 843699493cb82f7654af23e6b96f7e11922cbca3 Mon Sep 17 00:00:00 2001 From: FabrizioMoggio <87469955+FabrizioMoggio@users.noreply.github.com> Date: Tue, 16 Apr 2024 15:41:17 +0200 Subject: [PATCH 13/19] Add files via upload --- .../Traffic Influence/Traffic_Influence.yaml | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/code/API_definitions/Traffic Influence/Traffic_Influence.yaml b/code/API_definitions/Traffic Influence/Traffic_Influence.yaml index 14065ec4..2a887834 100644 --- a/code/API_definitions/Traffic Influence/Traffic_Influence.yaml +++ b/code/API_definitions/Traffic Influence/Traffic_Influence.yaml @@ -499,9 +499,9 @@ components: description: Correlation id for the different services. schema: type: string - ######################################################################### - # Events/Callbacks # - ######################################################################### + ######################################################################### + # Events/Callbacks # + ######################################################################### callbacks: onTrafficInfluenceChanged: # when data is sent, it will be sent to the `callbackUrl` provided @@ -706,9 +706,8 @@ components: type: string format: uuid example: "6B29FC40-CA47-1067-B31D-00DD010662DA" - description: A globally unique identifier associated with the - application. OP generates this identifier when the application is - submitted over NBI. + description: A globally unique identifier associated with theapplication. + OP generates this identifier when the application is submitted over NBI. ######################################################################## # Responses # ######################################################################## From ed030c4c76d855a0f83952c8f1fba0ba46933253 Mon Sep 17 00:00:00 2001 From: FabrizioMoggio <87469955+FabrizioMoggio@users.noreply.github.com> Date: Tue, 16 Apr 2024 15:52:44 +0200 Subject: [PATCH 14/19] Add files via upload --- code/API_definitions/Traffic Influence/Traffic_Influence.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/code/API_definitions/Traffic Influence/Traffic_Influence.yaml b/code/API_definitions/Traffic Influence/Traffic_Influence.yaml index 2a887834..a63cc026 100644 --- a/code/API_definitions/Traffic Influence/Traffic_Influence.yaml +++ b/code/API_definitions/Traffic Influence/Traffic_Influence.yaml @@ -706,7 +706,7 @@ components: type: string format: uuid example: "6B29FC40-CA47-1067-B31D-00DD010662DA" - description: A globally unique identifier associated with theapplication. + description: A globally unique identifier associated with theapplication. OP generates this identifier when the application is submitted over NBI. ######################################################################## # Responses # From 2a7577b65be837e576131cbc1fff37c54ed946b6 Mon Sep 17 00:00:00 2001 From: FabrizioMoggio <87469955+FabrizioMoggio@users.noreply.github.com> Date: Wed, 17 Apr 2024 15:37:02 +0200 Subject: [PATCH 15/19] Add files via upload --- .../Traffic Influence/Traffic_Influence.yaml | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/code/API_definitions/Traffic Influence/Traffic_Influence.yaml b/code/API_definitions/Traffic Influence/Traffic_Influence.yaml index a63cc026..6eed2cd9 100644 --- a/code/API_definitions/Traffic Influence/Traffic_Influence.yaml +++ b/code/API_definitions/Traffic Influence/Traffic_Influence.yaml @@ -229,7 +229,7 @@ servers: default: http://localhost:9091 description: API root basePath: - default: ti/v0 + default: traffic-influence/v0 description: Base path for the Traffic Influence API ############################################################################ # Tags # @@ -247,7 +247,7 @@ paths: get: security: - openId: - - ti:traffic-influences:read + - 'traffic-influence:traffic-influences:read' parameters: - $ref: '#/components/parameters/x-correlator' - in: query @@ -301,7 +301,7 @@ paths: - $ref: '#/components/parameters/x-correlator' security: - openId: - - ti:traffic-influences:write + - 'traffic-influence:traffic-influences:write' requestBody: description: Describes the request body required: true @@ -363,7 +363,7 @@ paths: - $ref: '#/components/parameters/x-correlator' security: - openId: - - ti:traffic-influences:read + - 'traffic-influence:traffic-influences:read' responses: '200': description: OK. @@ -398,7 +398,7 @@ paths: - $ref: '#/components/parameters/x-correlator' security: - openId: - - ti:traffic-influences:write + - 'traffic-influence:traffic-influences:write' requestBody: description: Describes the request body required: true @@ -448,7 +448,7 @@ paths: operationId: deleteTrafficInfluence security: - openId: - - ti:traffic-influences:write + - 'traffic-influence:traffic-influences:write' parameters: - $ref: '#/components/parameters/x-correlator' - name: callbackUrl @@ -888,4 +888,4 @@ components: example: status: 504 code: TIMEOUT - message: Request timeout exceeded. Try later \ No newline at end of file + message: Request timeout exceeded. Try later From 97c7b3c60f4d6b521de386caf1fc45d8639aa9a6 Mon Sep 17 00:00:00 2001 From: FabrizioMoggio <87469955+FabrizioMoggio@users.noreply.github.com> Date: Wed, 17 Apr 2024 15:42:45 +0200 Subject: [PATCH 16/19] Add files via upload --- .../Traffic Influence/Traffic_Influence.yaml | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/code/API_definitions/Traffic Influence/Traffic_Influence.yaml b/code/API_definitions/Traffic Influence/Traffic_Influence.yaml index 6eed2cd9..aeca3a41 100644 --- a/code/API_definitions/Traffic Influence/Traffic_Influence.yaml +++ b/code/API_definitions/Traffic Influence/Traffic_Influence.yaml @@ -247,7 +247,7 @@ paths: get: security: - openId: - - 'traffic-influence:traffic-influences:read' + - 'traffic-influence:traffic-influences:read' parameters: - $ref: '#/components/parameters/x-correlator' - in: query @@ -301,7 +301,7 @@ paths: - $ref: '#/components/parameters/x-correlator' security: - openId: - - 'traffic-influence:traffic-influences:write' + - 'traffic-influence:traffic-influences:write' requestBody: description: Describes the request body required: true @@ -363,7 +363,7 @@ paths: - $ref: '#/components/parameters/x-correlator' security: - openId: - - 'traffic-influence:traffic-influences:read' + - 'traffic-influence:traffic-influences:read' responses: '200': description: OK. @@ -398,7 +398,7 @@ paths: - $ref: '#/components/parameters/x-correlator' security: - openId: - - 'traffic-influence:traffic-influences:write' + - 'traffic-influence:traffic-influences:write' requestBody: description: Describes the request body required: true @@ -448,7 +448,7 @@ paths: operationId: deleteTrafficInfluence security: - openId: - - 'traffic-influence:traffic-influences:write' + - 'traffic-influence:traffic-influences:write' parameters: - $ref: '#/components/parameters/x-correlator' - name: callbackUrl From 901ec2091696b41d3547c2d7b71bc08674b7fd7c Mon Sep 17 00:00:00 2001 From: FabrizioMoggio <87469955+FabrizioMoggio@users.noreply.github.com> Date: Tue, 30 Apr 2024 10:29:34 +0200 Subject: [PATCH 17/19] Add files via upload From 8a42cebdfa326064f1c72b366f17d266bbfd8c52 Mon Sep 17 00:00:00 2001 From: FabrizioMoggio <87469955+FabrizioMoggio@users.noreply.github.com> Date: Fri, 3 May 2024 16:44:48 +0200 Subject: [PATCH 18/19] Add files via upload --- .../Traffic Influence/Traffic_Influence.yaml | 1783 +++++++++-------- 1 file changed, 892 insertions(+), 891 deletions(-) diff --git a/code/API_definitions/Traffic Influence/Traffic_Influence.yaml b/code/API_definitions/Traffic Influence/Traffic_Influence.yaml index aeca3a41..b08fb70d 100644 --- a/code/API_definitions/Traffic Influence/Traffic_Influence.yaml +++ b/code/API_definitions/Traffic Influence/Traffic_Influence.yaml @@ -1,891 +1,892 @@ ---- -openapi: 3.0.3 -############################################################################ -# API info # -############################################################################ -info: - title: OPAG-CAMARA Traffic Influence API - version: 0.9.3 - 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. - ## 1. 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. - ## 2. 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.\ - \ - **trafficFilters** - The Application can expose different service on different interfaces, with - this parameter it is possible to enable just some of those services maybe - for different sets of users.\ - \ - **Device** - A user Device can be provided as an input. 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.\ - \ - **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. - ## 3. 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. - ## 4. API Documentation - ## 4.1 Details - 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. - 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/ -############################################################################ -# Servers # -############################################################################ -servers: - - url: "{apiRoot}/{basePath}" - variables: - apiRoot: - default: http://localhost:9091 - description: API root - basePath: - default: traffic-influence/v0 - description: Base path 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:write' - 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:write' - 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: - 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' - trafficFilters: - type: array - items: - type: string - description: Indicates the packet filters of the IP flow. The source - IP is not required. It is retrived by the platoform according to - the TI API request. If no Traffic Influece resourse is created with - a specific Device, any IP will be routed to the Application. If a - Traffic Influece resource exists with a specific Device configured, - only the related IPs will be routed to the local instance of the - Application. The destination IP is not required,it is already known - by the platform thanks to the appId and appInstanceId parameters - that are used to retive the destination IP. The protocol must 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. - The destination port must be specified. - example: TCP 5060 - minItems: 1 - minItems: 1 - description: Identifies IP packet filters. To be used when a the - Application needs a traffic flow towards a specific EAS interface - 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: - type: object - minProperties: 1 - properties: - phoneNumber: - $ref: "#/components/schemas/PhoneNumber" - networkAccessIdentifier: - $ref: "#/components/schemas/NetworkAccessIdentifier" - ipv4Address: - $ref: "#/components/schemas/Ipv4Address" - ipv6Address: - $ref: "#/components/schemas/Ipv6Address" - description: Device identifier - NetworkAccessIdentifier: - type: string - example: "123456789@domain.com" - description: identifier for the End User formatted as string, it cab be - the user's email address. - PhoneNumber: - type: string - pattern: '^\+?[0-9]{5,15}$' - example: "123456789" - description: Subscriber number in E.164 format (starting with country - code). Optionally prefixed with '+'. - Ipv4Address: - type: string - format: ipv4 - example: "192.168.0.1" - description: IP of the device. A single IPv4 address may be specified in - dotted-quad form 1.2.3.4. Only this exact IP number will match the flow - control rule. - Ipv6Address: - type: string - format: ipv6 - example: "2001:db8:85a3:8d3:1319:8a2e:370:7344" - description: IP of the device. A single IPv6 address, following IETF 5952 - format, may be specified like 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 +--- +openapi: 3.0.3 +############################################################################ +# API info # +############################################################################ +info: + title: OPAG-CAMARA Traffic Influence API + version: 0.9.3 + 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. + ## 1. 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. + ## 2. 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.\ + \ + **trafficFilters** + The Application can expose different service on different interfaces, with + this parameter it is possible to enable just some of those services maybe + for different sets of users.\ + \ + **Device** + A user Device can be provided as an input. 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.\ + \ + **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. + ## 3. 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. + ## 4. API Documentation + ## 4.1 Details + 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. + 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/ +############################################################################ +# Servers # +############################################################################ +servers: + - url: "{apiRoot}/{basePath}" + variables: + apiRoot: + default: http://localhost:9091 + description: API root + basePath: + default: traffic-influence/v0 + description: Base path 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:write' + 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:write' + 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' + trafficFilters: + type: array + items: + type: string + description: Indicates the packet filters of the IP flow. The source + IP is not required. It is retrived by the platoform according to + the TI API request. If no Traffic Influece resourse is created with + a specific Device, any IP will be routed to the Application. If a + Traffic Influece resource exists with a specific Device configured, + only the related IPs will be routed to the local instance of the + Application. The destination IP is not required,it is already known + by the platform thanks to the appId and appInstanceId parameters + that are used to retive the destination IP. The protocol must 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. + The destination port must be specified. + example: TCP 5060 + minItems: 1 + minItems: 1 + description: Identifies IP packet filters. To be used when a the + Application needs a traffic flow towards a specific EAS interface + 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: + type: object + minProperties: 1 + properties: + phoneNumber: + $ref: "#/components/schemas/PhoneNumber" + networkAccessIdentifier: + $ref: "#/components/schemas/NetworkAccessIdentifier" + ipv4Address: + $ref: "#/components/schemas/Ipv4Address" + ipv6Address: + $ref: "#/components/schemas/Ipv6Address" + description: Device identifier + NetworkAccessIdentifier: + type: string + example: "123456789@domain.com" + description: identifier for the End User formatted as string, it cab be + the user's email address. + PhoneNumber: + type: string + pattern: '^\+?[0-9]{5,15}$' + example: "123456789" + description: Subscriber number in E.164 format (starting with country + code). Optionally prefixed with '+'. + Ipv4Address: + type: string + format: ipv4 + example: "192.168.0.1" + description: IP of the device. A single IPv4 address may be specified in + dotted-quad form 1.2.3.4. Only this exact IP number will match the flow + control rule. + Ipv6Address: + type: string + format: ipv6 + example: "2001:db8:85a3:8d3:1319:8a2e:370:7344" + description: IP of the device. A single IPv6 address, following IETF 5952 + format, may be specified like 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 53a2a74e3cd17aaf3838ec5598cead036525102d Mon Sep 17 00:00:00 2001 From: FabrizioMoggio <87469955+FabrizioMoggio@users.noreply.github.com> Date: Fri, 3 May 2024 16:53:15 +0200 Subject: [PATCH 19/19] Add files via upload --- code/API_definitions/Traffic Influence/Traffic_Influence.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/code/API_definitions/Traffic Influence/Traffic_Influence.yaml b/code/API_definitions/Traffic Influence/Traffic_Influence.yaml index b08fb70d..98feb7a1 100644 --- a/code/API_definitions/Traffic Influence/Traffic_Influence.yaml +++ b/code/API_definitions/Traffic Influence/Traffic_Influence.yaml @@ -484,7 +484,7 @@ paths: components: securitySchemes: openId: - description: to support Consent Management + description: to support Consent Management type: openIdConnect openIdConnectUrl: https://example.com/.well-known/openid-configuration