openapi: 3.0.0 ############################################################################ # API info # ############################################################################ info: title: OPAG-CAMARA Traffic Influence API version: 0.8.1 description: | ## Overview The reference scenario foresees a Service owned by a Developer, composed by one or more Service Producers provided by the Developer and deployed in different geographical locations on Telco Operator Edge sites (MEC sites) or in Cloud. The Service Producer, deployed at the Edge, is referred as Edge Application Server (EAS). The Traffic Influence API provides the fastest routing from the user equipment (e.g. a Smartphone) to the optimal Edge Application Server (EAS) Instance in a specific geographical location, installed in a Telco Operator Edge site. If a Service is offered by a Cloud Instance and by Edge Instances, the API can be used to route a selected set of users on the Edge Instance. ## 1. Introduction The Traffic Influence API provides the capability to establish the best connectivity, in terms of latency, in a specific geographical area, between the User Equipment (UE), e.g. the user’s smartphone, and the optimal Edge Application Server instance nearby. The Service architecture foresees one or more EASs and a component, the Application Function (AF), that is the API consumer. Invoking the TI API, the AF can create a "TrafficInfluence" resource specifying the desired request. The TI API provider implements the intent specified in the Traffic Influence resource. While the API is usually invoked to activate the fastest routing for any user, it can also be used to request the routing for a specific user. Invoking the API for each user (using the same "trafficInfluenceID"), the "TrafficInfluence" resource provides the requested routing for a set of users. ## 2. Quick Start The usage of the Traffic Influence API is based on the management of a "TrafficInfluence" resource, an object containing the intent requested invoking the Traffic Influence 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 API is asynchronous, a notification is available providing information about the status of the requested resource. For an Application (identified by "applicationId") many "TrafficInfluence" resources can be created, e.g. to add multiple users, regions or zones. Before starting to use the API, the developer needs to know about the below specified details: **Base-Url** The RESTful Traffic Influence API endpoint, for example [**https://tim-api.developer.tim.it/trafficinfluence**](https://tim-api.developer.tim.it/trafficinfluence) **Authentication** Configure security access keys such as OAuth 2.0 client credentials to be used by Client applications which will invoke the Traffic InfluenceAPI. **TrafficInfluence** This object represents the resource that carries the requirements from the user to be implemented. The Traffic Influence API is invoked for the life cycle management of this resource (CRUD). The resource contains the intents from the 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 pf time. **trafficInfluenceID** Identifier for the Traffic Influence resource. This parameter ir returned by the API and must be used to update it (e.g., adding new users or deleting it) **applicationFunctionId** Unique identifier for the Application Function (AF), 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 ore more Zones. A Zone is where the Edge Datacenters are 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 API must be invoked (PUT) of each region. New "TrafficInfluence" resources are created (with different "trafficInfluenceID"). All the created resources are aggregated by the Application (identified by "applicationId"). **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 Datacenters are located. To add more zones the API must be invoked (PUT) of each zone. New "TrafficInfluence" resources are created (with different "trafficInfluenceID"). All the created resources are aggregated by the Application (identified by "applicationId"). **applicationId** Unique Application identifier inside the Telco Operator Platform. **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. **usersId** Optionally a user can be provided as an input. To add more users the API must be invoked (PUT) of each user. New "TrafficInfluence" resources are created (with different "trafficInfluenceID"). All the created resources are aggregated by the Applicatoin (identified by "applicatoinId"). The routing toward the selected Application Instance is only applied for provided users. **Notification URL and token** Developers have a chance to specify callback URL on which notifications (eg. session termination) regarding the session can be received from the service provider. This is also an optional parameter. ## 3. Authentication and Authorization The Traffic Influence API makes use of the client credentials grant which is applicable for server to server use cases involving trusted partners or clients without any protected user data involved. In this method the API invoker client is registered as a confidential client with an authorization grant type of client\_credentials [2]. ## 4. API Documentation ## 4.1 Details The Traffic Influence (TI) API is consumed by an Application Function (AF) requesting for the fastest routing of the traffic flow from the User Equipments toward an instance of the Edge Application Server (EAS) in a Telco Operator Edge sites (MEC sites). When the EAS is onboarded and deployed in the MEC site, the Application is identified with a unique identifier (applicationId). Using the application identifier ("applicationId") and specifying a Zone or a Region, the Telco Operator Platform, autonomously identifies the best instance of the EAS toward 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 fastest routing should be available just for a set of users, the API must be invoked for each user also passing the same TrafficInfluce resource identifier ("trafficInfluenceID") 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 API must be invoked with the applicationId. 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 API must be invoked with the applicationId and the Zones and Regions identifiers. 3) activate the optimal routing for a specific set of users: the API can also be invoked with a user identifier ("userId"). The same TrafficInfluce resource identifier ("trafficInfluenceID") must be used in each call. license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html externalDocs: description: Product documentation at Camara url: https://github.com/camaraproject/ ############################################################################ # Security # ############################################################################ security: - oAuth2: - 'edge:traffic-influences:read' - 'edge:traffic-influences:write' ############################################################################ # 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 ############################################################################ # Paths # ############################################################################ paths: /traffic-influences: get: parameters: - in: query name: applicationId schema: type: string description: Not required. Used to select traffic influence resources filtered by applicationId tags: - Traffic Influence API GET Operation summary: Retries existing TrafficInfluence Resources description: Reads all of the active TrafficInfluence resources owned by the AF authenticated via oAuth2 operationId: GetTrafficInfluences responses: '200': description: Returns the information about existing TrafficInfluence resources. 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 POST Operation summary: Creates a new TrafficInfluence resource description: Gets in input an object containing the intents from the AF and creates a TrafficInfluence resourse accordingly. The trafficInfluenceID parameter, that is part of the object, must not be valorized when creating a new resource. It is automatically generated by the system and returned the response operationId: PostTrafficInfluence requestBody: description: Describes the request body required: true content: application/json: schema: $ref: '#/components/schemas/TrafficInfluence' responses: '201': description: TrafficInfluence resource created, the related object is returned with the resource ID (TIResource_id) and status (state) valorised, headers: 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' '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/{TIResource_id}: parameters: - name: TIResource_id 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: summary: read a specific TrafficInfluence resource identified by the TIResource_id value tags: - Traffic Influence API GET Operation responses: '200': description: OK. 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" put: tags: - TrafficInfluence API PUT Operation summary: updates a specific TrafficInfluence resource, identified by the TIResource_id value description: The resource identified by the TIResource_id value can be modified operationId: PutTrafficInfluence requestBody: description: Describes the request body required: true content: application/json: schema: $ref: '#/components/schemas/TrafficInfluence' 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 '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: summary: Delete an existing TrafficInfluence resource tags: - TrafficInfluence API Delete Operation parameters: - 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: '200': $ref: '#/components/responses/OkDeleted' '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: securitySchemes: oAuth2: type: oauth2 description: This API uses OAuth 2 [More info](https://api.example.com/docs/auth) flows: clientCredentials: tokenUrl: 'https://example.com/oauth/token' scopes: 'edge:traffic-influences:read': Grant read-only traffic-influences data 'edge:traffic-influences:write': Grant write access to traffic-influences data ####################################################### # 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: 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 '204': description: | Your server should return this HTTP status code if no longer interested in further updates ####################################################### # RESOURCES ####################################################### schemas: TrafficInfluenceNotification: type: object required: - trafficInfluenceChanged properties: trafficInfluenceChanged: $ref: "#/components/schemas/TrafficInfluence" TrafficInfluence: type: object properties: trafficInfluenceID: type: string description: Identifier for the Traffic Influence resource. This parameter ir returned by the API and must be used to update it (e.g., adding new users or deleting it) passing it as TIResource_id value in the API call. applicationFunctionId: type: string description: Unique Identifier of the Application Function, the TI API consumer. applicationId: type: string example: "Virtual_Reality_Arena" description: Unique ID representing the Edge Application region: $ref: '#/components/schemas/types_region_Id' zone: $ref: '#/components/schemas/types_zone_Id' userId: $ref: '#/components/schemas/userId' state: type: string enum: - 'ordered' - 'created' - 'active' - 'not active' - 'error' - 'deleted' trafficFilters: type: array items: $ref: '#/components/schemas/FlowInfo' 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: - applicationFunctionId - applicationId ####################################################### # TYPES ####################################################### types_zone_Id: description: | Unique identifier representing a zone type: string additionalProperties: false types_region_Id: description: | Unique identifier representing a region type: string additionalProperties: false userId: description: User equipment identifier, it is composed by a value and a type for that value type: object minProperties: 1 properties: UEIdentityType: $ref: "#/components/schemas/types_UEIdentityType" UEIdentity: $ref: "#/components/schemas/types_UEIdentity" types_UEIdentityType: description: Type of User Equipment identifier used in `UEIdentity`. type: string enum: - IPAddress - MSISDN - IMEI - MDN - GPSI types_UEIdentity: description: Identifier value for User Equipment. The type of identifier is defined by the 'UEIdentityType' parameter. type: string FlowInfo: type: object properties: flowId: type: integer description: Indicates the IP flow. flowDescriptions: type: array items: type: string description: Indicates the packet filters of the IP flow. The source IP is according to the TI API request, any IP (if no userId is provided) or the IP related to userId so it doesn't need to be specified int flowDescription. The protocol is identified by a number as defined by IANA (https://www.iana.org/assignments/protocol-numbers/protocol-numbers.xhtml), e.g. 1 (UDP) or 2 (TCP). The destination IP and port must be specified. example: protocol 1 to 10.98.0.0/24 5060 minItems: 1 maxItems: 2 required: - flowId ###################################################### # RESPONSES ####################################################### ErrResponse: type: object properties: status: type: string example: OK message: type: string example: OK ErrorInfo: 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 content: application/json: schema: $ref: '#/components/schemas/ErrResponse' example: status: ERROR message: Resource not found GenericError: description: An unknow error has occurred content: application/json: schema: $ref: '#/components/schemas/ErrResponse' example: status: ERROR message: Generic error BackendConnTimeout: description: Connection timeout towards backend service has occurred content: application/json: schema: $ref: '#/components/schemas/ErrResponse' example: status: ERROR message: Backend connection timeout OkDeleted: description: The resource has been successfully deleted content: application/json: example: status: OK message: Deleted Generic400: description: Invalid input content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" example: code: INVALID_INPUT message: "Schema validation failed at ..." Generic401: description: Unauthorized content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" example: code: UNAUTHORIZED message: "Authorization failed: ..." Generic403: description: Forbidden content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" example: code: FORBIDDEN message: "Operation not allowed: ..." SessionNotFound404: description: Session not found content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" example: code: NOT_FOUND message: "Session Id does not exist" Generic503: description: Service unavailable content: application/json: schema: $ref: "#/components/schemas/ErrorInfo" example: code: SERVICE_UNAVALIBLE message: "Service unavailable"