openapi: 3.0.3 info: title: Global System for Mobile Communications GSMA Camara Project Traffic Influence API version: wip description: >- The Traffic Influence API provides the capability to establish the optimal routing, in terms of latency, in a specific geographical area, between the user device, e.g. the users smartphone, and the optimal Edge Application Server (EAS) instance nearby. If the user device is detected by the developer to have moved into a different geographical location, the Traffic Influence API can be invoked again to get the optimal routing in the new location. license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html contact: email: project-email@sample.com externalDocs: description: Product documentation at Camara url: https://github.com/camaraproject/EdgeCloud servers: - url: '{apiRoot}/traffic-influence/vwip' variables: apiRoot: default: http://localhost:9091 description: API root for the Traffic Influence API tags: - name: Traffic Influence API Read description: Reads existing TrafficInfluence resources - name: Traffic Influence API Write description: Creates of modifies a TrafficInfluence resource 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: Global System for Mobile Communications 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: Global System for Mobile Communications 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' '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' 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: >- Global System for Mobile Communications 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' '401': $ref: '#/components/responses/Generic401' '403': $ref: '#/components/responses/Generic403' '404': $ref: '#/components/responses/ResNotFound' '500': $ref: '#/components/responses/GenericError' '503': $ref: '#/components/responses/Generic503' '504': $ref: '#/components/responses/BackendConnTimeout' patch: tags: - Traffic Influence API Write summary: >- Global System for Mobile Communications updates a specific TrafficInfluence resource, identified by the trafficInfluenceID value. description: >- The resource identified by the trafficInfluenceID value can be modified. Before the PATCH can be invoked the status (state) of the resource must be "active". If not an errore code 409 (DENIED_WAIT) is returned. operationId: patchTrafficInfluence parameters: - $ref: '#/components/parameters/x-correlator' security: - openId: - traffic-influence:traffic-influences:update requestBody: description: Describes the request body required: true content: application/json: schema: $ref: '#/components/schemas/PatchTrafficInfluence' responses: '200': description: >- TrafficInfluence resource edited, the related object is returned, the status (state) is updated. content: application/json: schema: $ref: '#/components/schemas/TrafficInfluence' headers: Location: description: Link to the created traffic influence resource schema: type: string description: Link to the created traffic influence resource x-correlator: $ref: '#/components/headers/x-correlator' '400': $ref: '#/components/responses/Generic400' '401': $ref: '#/components/responses/Generic401' '403': $ref: '#/components/responses/Generic403' '404': $ref: '#/components/responses/ResNotFound' '500': $ref: '#/components/responses/GenericError' '503': $ref: '#/components/responses/Generic503' '504': $ref: '#/components/responses/BackendConnTimeout' callbacks: onTrafficInfluenceChanged: $ref: '#/components/callbacks/onTrafficInfluenceChanged' delete: tags: - Traffic Influence API Write summary: Global System for Mobile Communications Delete an existing TrafficInfluence resource description: >- invoked by the API Consumer to stop influencing the traffic, deleting a TrafficInfluence resource previously created. operationId: deleteTrafficInfluence security: - openId: - traffic-influence:traffic-influences:delete parameters: - $ref: '#/components/parameters/x-correlator' - name: callbackUrl in: query required: false description: | the location where updated data will be sent. Must be network accessible by the source server schema: type: string format: uri example: https://my-notification-server.com responses: '202': $ref: '#/components/responses/OkDeletionInProgress' '401': $ref: '#/components/responses/Generic401' '403': $ref: '#/components/responses/Generic403' '404': $ref: '#/components/responses/ResNotFound' '503': $ref: '#/components/responses/Generic503' '504': $ref: '#/components/responses/BackendConnTimeout' callbacks: onTrafficInfluenceChanged: $ref: '#/components/callbacks/onTrafficInfluenceChanged' 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 callbacks: onTrafficInfluenceChanged: '{$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' 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' edgeCloudRegion: $ref: '#/components/schemas/EdgeCloudRegion' edgeCloudZoneId: $ref: '#/components/schemas/EdgeCloudZoneId' device: $ref: '#/components/schemas/Device' state: type: string description: >- it reports the state of the TrafficInfluence resource. When first invoked, the resource is 'ordered'. When the platforms prepares the resource, it is 'created'. When the new routing is enabled in the network, the state is 'active'. If an error occurs in the resource creation or in its activation, the state is 'error'. When the DELETE method is invoked the state is 'deletion in progress'. After the resource is deleted (as a consequence of the previous invokation of the DELETE method) the state is 'deleted'. enum: - ordered - created - active - error - deletion in progress - deleted sourceTrafficFilters: description: >- Public source port used by the device for flows to which the requested traffic influence should apply. Traffic influence will be applied to the flow between "sourcePort" and the Application Server address and port specified in "destinationTrafficFilters". type: object properties: sourcePort: allOf: - $ref: '#/components/schemas/Port' destinationTrafficFilters: description: >- Identifies the destination IP packet filters. To be used when it is needed a traffic flow towards a specific EAS interface identified by a protocol and a port. Also the Protocol (e.g. TCP or UDP) can be specified. type: object properties: destinationPort: allOf: - $ref: '#/components/schemas/Port' destinationProtocol: allOf: - $ref: '#/components/schemas/Protocol' notificationUri: type: string description: >- Defines the callback uri which should be notified in asynchronous way when the state for the requested resources changes (i.e. ordered to activated) notificationAuthToken: type: string description: Authentification token for callback API required: - apiConsumerId - appId PatchTrafficInfluence: description: >- inherits from TrafficInfluence and restricts the access to certain parameters. Only some paramter can be indeed modified with the PATCH operation. allOf: - $ref: '#/components/schemas/TrafficInfluence' properties: trafficInfluenceID: readOnly: true apiConsumerId: readOnly: true appId: readOnly: true state: readOnly: true PostTrafficInfluence: allOf: - $ref: '#/components/schemas/TrafficInfluence' properties: trafficInfluenceID: readOnly: true state: readOnly: true TrafficInfluenceNotification: type: object description: >- Notifican channel for changes in the TrafficInfluence resource. It returnes back the TrafficInfluece resource with the updated status ("state") and also proivides back the identifier of the selected EAS instance. allOf: - $ref: '#/components/schemas/TrafficInfluence' properties: selected_appInstanceId: $ref: '#/components/schemas/AppInstanceId' EdgeCloudZoneId: type: string format: uuid description: | Unique identifier created by the Edge Cloud Platform to identify an Edge Cloud Zone within an Edge Cloud EdgeCloudRegion: type: string description: | Human readable name of the geographical Edge Cloud Region of the Edge Cloud. Defined by the Edge Cloud Provider. additionalProperties: false Device: description: | End-user equipment able to connect to a mobile network. Examples of devices include smartphones or IoT sensors/actuators. The developer can choose to provide the below specified device identifiers: * `ipv4Address` * `ipv6Address` * `phoneNumber` * `networkAccessIdentifier` NOTE1: the MNO might support only a subset of these options. The API invoker can provide multiple identifiers to be compatible across different MNOs. In this case the identifiers MUST belong to the same device. NOTE2: for the Commonalities release v0.4, we are enforcing that the networkAccessIdentifier is only part of the schema for future-proofing, and CAMARA does not currently allow its use. After the CAMARA meta-release work is concluded and the relevant issues are resolved, its use will need to be explicitly documented in the guidelines. type: object properties: phoneNumber: $ref: '#/components/schemas/PhoneNumber' networkAccessIdentifier: $ref: '#/components/schemas/NetworkAccessIdentifier' ipv4Address: $ref: '#/components/schemas/DeviceIpv4Addr' ipv6Address: $ref: '#/components/schemas/DeviceIpv6Address' minProperties: 1 PhoneNumber: description: >- A public identifier addressing a telephone subscription. In mobile networks it corresponds to the MSISDN (Mobile Station International Subscriber Directory Number). In order to be globally unique it has to be formatted in international format, according to E.164 standard, prefixed with '+'. type: string pattern: ^\+[1-9][0-9]{4,14}$ example: '+123456789' NetworkAccessIdentifier: description: >- A public identifier addressing a subscription in a mobile network. In 3GPP terminology, it corresponds to the GPSI formatted with the External Identifier ({Local Identifier}@{Domain Identifier}). Unlike the telephone number, the network access identifier is not subjected to portability ruling in force, and is individually managed by each operator. type: string example: 123456789@domain.com DeviceIpv4Addr: type: object description: | The device should be identified by either the public (observed) IP address and port as seen by the application server, or the private (local) and any public (observed) IP addresses in use by the device (this information can be obtained by various means, for example from some DNS servers). If the allocated and observed IP addresses are the same (i.e. NAT is not in use) then the same address should be specified for both publicAddress and privateAddress. If NAT64 is in use, the device should be identified by its publicAddress and publicPort, or separately by its allocated IPv6 address (field ipv6Address of the Device object) In all cases, publicAddress must be specified, along with at least one of either privateAddress or publicPort, dependent upon which is known. In general, mobile devices cannot be identified by their public IPv4 address alone. properties: publicAddress: $ref: '#/components/schemas/SingleIpv4Addr' privateAddress: $ref: '#/components/schemas/SingleIpv4Addr' publicPort: $ref: '#/components/schemas/Port' anyOf: - required: - publicAddress - privateAddress - required: - publicAddress - publicPort example: publicAddress: 84.125.93.10 publicPort: 59765 SingleIpv4Addr: description: A single IPv4 address with no subnet mask type: string format: ipv4 example: 84.125.93.10 Port: description: TCP or UDP port number type: integer minimum: 0 maximum: 65535 Protocol: description: >- The protocol for the influeced flow. It can be specified and it is identified by a string according to the column Keyword as defined by IANA (https://www.iana.org/assignments/protocol-numbers/\ protocol-numbers.xhtml), e.g. UDP or TCP. type: string example: TCP DeviceIpv6Address: description: | The device should be identified by the observed IPv6 address, or by any single IPv6 address from within the subnet allocated to the device (e.g. adding ::0 to the /64 prefix). type: string format: ipv6 example: 2001:db8:85a3:8d3:1319:8a2e:370:7344 AppInstanceId: type: string format: uuid description: >- A globally unique identifier associated with a running instance of an application. OP generates this identifier. AppId: type: string format: uuid example: 6B29FC40-CA47-1067-B31D-00DD010662DA description: >- A globally unique identifier associated with theapplication. OP generates this identifier when the application is submitted over NBI. 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. Generic409: description: Conflict headers: x-correlator: $ref: '#/components/headers/x-correlator' content: application/json: schema: $ref: '#/components/schemas/ErrorInfo' examples: GENERIC_409_ABORTED: description: Concurreny of processes of the same nature/scope value: status: 409 code: ABORTED message: Concurrency conflict. GENERIC_409_ALREADY_EXISTS: description: Trying to create an existing resource value: status: 409 code: ALREADY_EXISTS message: The resource that a client tried to create already exists. GENERIC_409_CONFLICT: description: Duplication of an existing resource value: status: 409 code: CONFLICT message: A specified resource duplicate entry found. GENERIC_409_DENIED_WAIT: description: Patch denial if the previous intent is not yet fulfilled. value: status: 409 code: DENIED_WAIT message: >- It is not possibile to modify the Traffic Influence resource because it is still under provisioning. The resource can be modified when it is fully implemented and activated. Please wait for the resource status (state) to be "active" before trying to update it. 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