Merge pull request #249 from FabrizioMoggio/rel-0.9.5

Rel 0.9.5

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
@@ -90,30 +90,30 @@ info:
     Before starting to use the TI API, the developer needs to know about the
     below specified details:\
     \
-    **Base-Url**
+    **Base-Url:**
     The RESTful TI API endpoint, for example
     [**https://tim-api.developer.tim.it/trafficinfluence**](https://tim-api.\
     developer.tim.it/trafficinfluence)\
     \
-    **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**
+    **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**
+    **apiConsumerId:**
     Unique identifier for the TI API Consumer.\
     \
-    **region**
+    **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
@@ -125,7 +125,7 @@ info:
     "trafficInfluenceID"). All the created resources are aggregated by the
     Application (identified by "appId").\
     \
-    **zone**
+    **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
@@ -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,11 @@ 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
+    - introduced sourceTrafficFilters and modified trafficFilters into
+    destinationTrafficFilters
   license:
     name: Apache 2.0
     url: https://www.apache.org/licenses/LICENSE-2.0.html
@@ -641,28 +654,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 +733,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
-      minProperties: 1
       properties:
         phoneNumber:
           $ref: "#/components/schemas/PhoneNumber"
         networkAccessIdentifier:
           $ref: "#/components/schemas/NetworkAccessIdentifier"
         ipv4Address:
-          $ref: "#/components/schemas/Ipv4Address"
+          $ref: "#/components/schemas/DeviceIpv4Addr"
         ipv6Address:
-          $ref: "#/components/schemas/Ipv6Address"
-      description: Device identifier
+          $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]"
-      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:
+    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: "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:
+      example: "84.125.93.10"
+    PortsSpec:
+      description: Specification of several TCP or UDP ports
+      type: object
+      minProperties: 1
+      properties:
+        ranges:
+          description: Range of TCP or UDP ports
+          type: array
+          minItems: 1
+          items:
+            type: object
+            required:
+              - from
+              - to
+            properties:
+              from:
+                $ref: "#/components/schemas/Port"
+              to:
+                $ref: "#/components/schemas/Port"
+    Port:
+      description: TCP or UDP port number
+      type: integer
+      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"
-      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
+      example: 2001:db8:85a3:8d3:1319:8a2e:370:7344
     AppInstanceId:
       type: string
       format: uuid