GSMA Camara Project Traffic Influence API

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: [email protected]
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: [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
    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