Rel 0.9.

Author: FabrizioMoggio

code/API_definitions/Traffic_Influence.yaml

@@ -4,8 +4,8 @@ openapi: 3.0.3
 #                                     API info                             #
 ############################################################################
 info:
-  title: OPAG-CAMARA Traffic Influence API
-  version: 0.9.4-wip
+  title: Traffic Influence API
+  version: 0.9.5-wip
   description: |
     ## Overview
     The reference scenario foresees a Service, composed by one or more Service
@@ -135,32 +135,40 @@ info:
     "trafficInfluenceID"). All the created resources are aggregated by the
     Application (identified by "appId").\
     \
-    **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**
+    **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.\
+    **sourceTrafficFilters:**
+    The traffic can be from a specific application port in the Device.\
     \
-    **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.\
+    **destinationTrafficFilters:**
+    The Application can expose different service on different interfaces, 
+    identified by port and protocol, with this parameter it is possible to 
+    route the traffic just toward some of those services maybe for different
+    sets of users.\
     \
-    **Notification URL and token**
+    **Device:**
+    An user Device can be provided as an input. The Device can be identified by
+    the phone number (phoneNumber), an external identifier
+    (networkAccessIdentifier) or by its IP Address (Ipv4Address, Ipv6Address)
+    also specifying a Port. For IP address both the private (as seen from inside
+    the Device) and the public (as seen over Internet by a server connected to
+    the Device) can be used. To add more users the TI API must be invoked (POST)
+    of each user Device. New "TrafficInfluence" resources are created (with
+    different "trafficInfluenceID"). All the created resources are aggregated by
+    the Application (identified by "appId"). The routing toward the selected
+    Application instance is only applied for provided user Devices.\
+    \
+    **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.
@@ -270,6 +278,9 @@ info:
     - Modified CAMARA URL to refer to the Edge Cloud Repository
     - OAS version now includes "-wip" extension
     - simplified "Servers" section and included "vwip" as version
+    - Updated documentation to better specify how to identify a Device
+    - Updated the Device parameter according to CAMARA_common.yaml
+    - change API name in YAML
   license:
     name: Apache 2.0
     url: https://www.apache.org/licenses/LICENSE-2.0.html
@@ -641,28 +652,29 @@ components:
             - '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
+        sourceTrafficFilters:
+          description: Ports used locally by the device for flows to which
+           the requested traffic influence should apply. If omitted, then the
+           traffic influence will apply to all flows between the device and the
+           specified application server address and ports.
+          type: object
+          properties:
+            sourcePort:           
+              allOf:
+                - $ref: "#/components/schemas/PortsSpec"
+        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/PortsSpec"
+            destinationProtocol:
+              allOf:            
+                - $ref: "#/components/schemas/Protocol"
         notificationUri:
           type: string
           description: Defines the callback uri which should be notified in
@@ -719,42 +731,123 @@ components:
       type: string
       additionalProperties: false
     Device:
+     description: |
+      End-user equipment able to connect to a mobile network. Examples of
+        devices include smartphones or IoT sensors/actuators.
+        The developer can choose to provide the below specified device
+        identifiers:
+        * `ipv4Address`
+        * `ipv6Address`
+        * `phoneNumber`
+        * `networkAccessIdentifier`
+        NOTE: the MNO might support only a subset of these options. The API
+        invoker can provide multiple identifiers to be compatible across
+        different MNOs. In this case the identifiers MUST belong to the same
+        device.
+     type: object
+     properties:
+      phoneNumber:
+       $ref: "#/components/schemas/PhoneNumber"
+      networkAccessIdentifier:
+       $ref: "#/components/schemas/NetworkAccessIdentifier"
+      ipv4Address:
+       $ref: "#/components/schemas/DeviceIpv4Addr"
+      ipv6Address:
+       $ref: "#/components/schemas/DeviceIpv6Address"
+     minProperties: 1
+    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: "[email protected]"
+    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"
+    PortsSpec:
+      description: Specification of several TCP or UDP ports
       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: "[email protected]"
-      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
+        ranges:
+          description: Range of TCP or UDP ports
+          type: array
+          minItems: 1
+          items:
+            type: object
+            required:
+              - from
+              - to
+            properties:
+              from:
+                $ref: "#/components/schemas/Port"
+              to:
+                $ref: "#/components/schemas/Port"
+    Port:
+     description: TCP or UDP port number
+     type: integer
+     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