qos-profiles.yaml

openapi: 3.0.3
info:
  title: QoS Profiles
  description: |
    The QoS Profiles API allows the discovery of Quality of Service (QoS) profiles and its characteristics.

    # Introduction

    QoS Profiles are used in conjunction with other Quality-On-Demand APIs, to offer the application developers the capability to request for stable latency (reduced jitter) or throughput for some specified application data flows between application clients (within a user device) and Application Servers (backend services). The developer has a pre-defined set of Quality of Service (QoS) profiles which they could choose from depending on their latency or throughput requirements. The QoS profiles are defined by the network operator and are mapped to the connectivity characteristics of the network.

    # API functionality

    The QoS Profiles API provides the following functionality:
    - Discovery of all QoS profiles offered by the network operator
    - Retrieve the characteristics of a specific QoS profile by name

    How QoS profiles are mapped to connectivity characteristics are subject to agreements between the communication service provider and the API invoker. Within the CAMARA project, you can find a sample for such a mapping of QoS profiles. [CAMARA QoS Profiles Mapping Table (REFERENCE DRAFT)](https://github.com/camaraproject/QualityOnDemand/blob/main/documentation/API_documentation/QoSProfile_Mapping_Table.md)

    # Authorization and Authentication

    [Camara Security and Interoperability Profile](https://github.com/camaraproject/IdentityAndConsentManagement/blob/main/documentation/CAMARA-Security-Interoperability.md) provides details on how a client requests an access token.

    Which specific authorization flows are to be used will be determined during onboarding process, happening between the API Client and the Telco Operator exposing the API, taking into account the declared purpose for accessing the API, while also being subject to the prevailing legal framework dictated by local legislation.

    It is important to remark that in cases where personal user data is processed by the API, and users can exercise their rights through mechanisms such as opt-in and/or opt-out, the use of 3-legged access tokens becomes mandatory. This measure ensures that the API remains in strict compliance with user privacy preferences and regulatory obligations, upholding the principles of transparency and user-centric data control.

    # Identifying a device from the access token

    This specification defines the `device` object field as optional in API requests, specifically in cases where the API is accessed using a 3-legged access token, and the device can be uniquely identified by the token. This approach simplifies API usage for API consumers by relying on the device information associated with the access token used to invoke the API.

    ## Handling of device information:

    ### Optional device object for 3-legged tokens:

    - When using a 3-legged access token, the device associated with the access token must be considered as the device for the API request. This means that the device object is not required in the request, and if included it must identify the same device, therefore **it is recommended NOT to include it in these scenarios** to simplify the API usage and avoid additional validations.

    ### Validation mechanism:

    - The server will extract the device identification from the access token, if available.
    - If the API request additionally includes a `device` object when using a 3-legged access token, the API will validate that the device identifier provided matches the one associated with the access token.
    - If there is a mismatch, the API will respond with a 403 - INVALID_TOKEN_CONTEXT error, indicating that the device information in the request does not match the token.

    ### Error handling for unidentifiable devices:

    - If the `device` object is not included in the request and the device information cannot be derived from the 3-legged access token, the server will return a 422 `UNIDENTIFIABLE_DEVICE` error.

    ### Restrictions for tokens without an associated authenticated identifier:

    - For scenarios which do not have a single device identifier associated to the token during the authentication flow, e.g. 2-legged access tokens, the `device` object MUST be provided in the API request. This ensures that the device identification is explicit and valid for each API call made with these tokens.

    # Further info and support

    (FAQs will be added in a later version of the documentation)

  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  version: 0.11.0
  x-camara-commonalities: 0.4.0


externalDocs:
  description: Project documentation at Camara
  url: https://github.com/camaraproject/QualityOnDemand

servers:
  - url: "{apiRoot}/qos-profiles/v0.11"
    variables:
      apiRoot:
        default: http://localhost:9091
        description: API root, defined by the service provider, e.g. `api.example.com` or `api.example.com/somepath`

tags:
  - name: QoS Profiles
    description: Manage QoS Profiles

paths:
  /retrieve-qos-profiles:
    post:
      tags:
        - QoS Profiles
      summary: Retrieve QoS profiles
      description: |
        Returns all QoS Profiles that match the given criteria.
        **NOTES:**
        - The access token may be either a 2-legged or 3-legged access token.
        - If the access token is 3-legged, all returned QoS Profiles will be available to all end users associated with the access token.

      security:
        - openId:
            - qos-profiles:read
      operationId: retrieveQoSProfiles
      parameters:
        - $ref: "#/components/parameters/x-correlator"
      requestBody:
        description: Parameters to query QoS Profiles for a given device
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/QosProfileDeviceRequest"
        required: true
      responses:
        "200":
          description: Contains information about QoS Profiles
          headers:
            x-correlator:
              $ref: '#/components/headers/x-correlator'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/QosProfile"
        "400":
          $ref: "#/components/responses/Generic400"
        "401":
          $ref: "#/components/responses/Generic401"
        "403":
          $ref: "#/components/responses/Generic403"
        "404":
          $ref: "#/components/responses/GenericDevice404"
        "422":
          $ref: "#/components/responses/Generic422"
        "429":
          $ref: "#/components/responses/Generic429"
        "500":
          $ref: "#/components/responses/Generic500"
        "503":
          $ref: "#/components/responses/Generic503"

  /qos-profiles/{name}:
    get:
      tags:
        - QoS Profiles
      summary: "Get QoS Profile for a given name"
      operationId: getQosProfile
      description: |
        Returns a QoS Profile that matches the given name.

        The access token may be either a 2-legged or 3-legged access token. If the access token is 3-legged, a QoS Profile is only returned if available to all end users associated with the access token.

      security:
        - openId:
            - qos-profiles:read
      parameters:
        - name: name
          in: path
          description: Qos Profile name
          required: true
          schema:
            $ref: "#/components/schemas/QosProfileName"
        - $ref: "#/components/parameters/x-correlator"
      responses:
        "200":
          description: Contains information about QoS Profiles
          headers:
            x-correlator:
              $ref: '#/components/headers/x-correlator'
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/QosProfile"
        "400":
          $ref: "#/components/responses/Generic400"
        "401":
          $ref: "#/components/responses/Generic401"
        "403":
          $ref: "#/components/responses/Generic403"
        "404":
          $ref: "#/components/responses/Generic404"
        "429":
          $ref: "#/components/responses/Generic429"
        "500":
          $ref: "#/components/responses/Generic500"
        "503":
          $ref: "#/components/responses/Generic503"

components:
  securitySchemes:
    openId:
      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

  schemas:
    QosProfile:
      description: |
        Data type with attributes of a QosProfile
      type: object
      properties:
        name:
          $ref: "#/components/schemas/QosProfileName"
        description:
          description: |
            A description of the QoS profile.
          type: string
          example: "QoS profile for video streaming"
        status:
          $ref: "#/components/schemas/QosProfileStatusEnum"
        targetMinUpstreamRate:
          description: |
            This is the target minimum upstream rate for the QoS profile.
            For 5G networks 3GPP Guaranteed Bit Rate (GBR) refers to a dedicated, fixed data rate assigned to
            specific services, ensuring a minimum performance level. As per 3GPP TS 23.203,
            GBR is a QoS parameter used to manage traffic classes in mobile networks. It
            provides a stable data rate for latency-sensitive applications, such as voice calls or
            video streaming, helping maintain a consistent user experience. When this attribute is set
            this could imply that a GBR QCI is used, though mechanisms on the network can be used to
            ensure a minimum performance level without using a GBR QCI.
            The committed data rate allocated to specific services, ensuring a consistent level of
            performance. For DOCSIS networks, the "Minimum Reserved Traffic Rate" is defined in the
            DOCSIS 3.1 - MAC and Upper Layer Protocols Interface Specification"
            and it ensures a consistent level of performance for specific services within the network.
          allOf:
            - $ref: "#/components/schemas/Rate"
        maxUpstreamRate:
          description: |
            The maximum best effort data
          allOf:
            - $ref: "#/components/schemas/Rate"
        maxUpstreamBurstRate:
          description: |
            When defined, this is the maximum upstream burst rate for the QoS profile, that will enable
            the network to burst data at a higher rate than the maxUpstreamRate for a period of time.
          allOf:
            - $ref: "#/components/schemas/Rate"
        targetMinDownstreamRate:
          description: |
            This is the target minimum downstream rate for the QoS profile.
            For 5G networks 3GPP Guaranteed Bit Rate (GBR) refers to a dedicated, fixed data rate assigned to
            specific services, ensuring a minimum performance level. As per 3GPP TS 23.203,
            GBR is a QoS parameter used to manage traffic classes in mobile networks. It
            provides a stable data rate for latency-sensitive applications, such as voice calls or
            video streaming, helping maintain a consistent user experience.  When this attribute is set
            this could imply that a GBR QCI is used, though mechanisms on the network can be used to
            ensure a minimum performance level without using a GBR QCI.
            The committed data rate allocated to specific services, ensuring a consistent level of
            performance. DOCSIS networks, the "Minimum Reserved Traffic Rate" is defined in the
            DOCSIS 3.1 - MAC and Upper Layer Protocols Interface Specification"
            and it ensures a consistent level of performance for specific services within the network.
          allOf:
            - $ref: "#/components/schemas/Rate"
        maxDownstreamRate:
          description: |
            The maximum best effort rate
          allOf:
            - $ref: "#/components/schemas/Rate"
        maxDownstreamBurstRate:
          description: |
            When defined, this is the maximum downstream burst rate for the QoS profile, that will enable
            the network to burst data at a higher rate than the maxDownstreamRate for a period of time.
            This can result in improved user experience when there is additional network capacity.
            For instance, when a user is streaming a video, the network can burst data at a higher rate
            to fill the buffer, and then return to the maxUpstreamRate once the buffer is full.
          allOf:
            - $ref: "#/components/schemas/Rate"
        minDuration:
          description: |
            The shortest time period that this profile can be deployed.
          allOf:
            - $ref: "#/components/schemas/Duration"
        maxDuration:
          description: |
            The maximum time period that this profile can be deployed.
            Overall session duration must not exceed this value. This includes the initial requested duration plus any extensions.
          allOf:
            - $ref: "#/components/schemas/Duration"
        priority:
          type: integer
          example: 20
          description: |
            Priority levels allow efficient resource allocation and ensure optimal performance
            for various services in each technology, with the highest priority traffic receiving
            preferential treatment.
            The lower value the higher priority.
            Not all access networks use the same priority range, so this priority will be
            scaled to the access network's priority range.
          format: int32
          minimum: 1
          maximum: 100
        packetDelayBudget:
          description: |
            The packet delay budget is the maximum allowable one-way latency between the customer's device
            and the gateway from the operator's network to other networks. By limiting the delay, the network
            can provide an acceptable level of performance for various services, such as voice calls,
            video streaming, and data.
            The end-to-end or round trip latency will be about two times this value plus the latency not controlled
            by the operator
          allOf:
            - $ref: "#/components/schemas/Duration"
        jitter:
          description: |
            The jitter requirement aims to limit the maximum variation in round-trip
            packet delay for the 99th percentile of traffic, following ITU Y.1540
            standards. It considers only acknowledged packets in a session, which are
            packets that receive a confirmation of receipt from the recipient (e.g.,
            using TCP). This requirement helps maintain consistent latency, essential
            for real-time applications such as VoIP, video calls, and gaming.
          allOf:
            - $ref: "#/components/schemas/Duration"
        packetErrorLossRate:
          type: integer
          description: |
            The exponential power of the allowable error loss rate 10^(-N).
            For instance 3 would be an error loss rate of 10 to the power of -3 (0.001)

            For 5G network the 3GPP specification TS 23.203 defines the packet error loss rate QCI attribute. It
            describes the Quality of Service (QoS) Class Identifier (QCI) parameters used to
            differentiate traffic classes in mobile networks, ensuring appropriate resource
            allocation and performance for various services.

            The packet error loss rate is one of the QCI attributes, providing information on the
            acceptable packet loss rate for a specific traffic class. This attribute helps maintain
            the desired performance level for services like voice calls, video streaming, or data
            transfers within the 3GPP mobile network.
          format: int32
          minimum: 1
          maximum: 10
          example: 3
      required:
        - name
        - status

    QosProfileName:
      description: |
        A unique name for identifying a specific QoS profile.
        This may follow different formats depending on the service providers implementation.
        Some options addresses:
          - A UUID style string
          - Support for predefined profiles QOS_S, QOS_M, QOS_L, and QOS_E
          - A searchable descriptive name
      type: string
      example: QCI_1_voice
      minLength: 3
      maxLength: 256
      format: string
      pattern: "^[a-zA-Z0-9_.-]+$"

    Rate:
      description: Specification of rate
      type: object
      properties:
        value:
          description: Quantity of rate
          type: integer
          example: 10
          format: int32
          minimum: 0
          maximum: 1024
        unit:
          $ref: "#/components/schemas/RateUnitEnum"

    Duration:
      description: Specification of duration
      type: object
      properties:
        value:
          description: Quantity of duration
          type: integer
          example: 12
          format: int32
          minimum: 1
        unit:
          $ref: "#/components/schemas/TimeUnitEnum"

    TimeUnitEnum:
      description: Units of time
      type: string
      enum:
        - Days
        - Hours
        - Minutes
        - Seconds
        - Milliseconds
        - Microseconds
        - Nanoseconds

    QosProfileStatusEnum:
      description: |
        The current status of the QoS Profile
        - `ACTIVE`- QoS Profile is available to be used
        - `INACTIVE`- QoS Profile is not currently available to be deployed
        - `DEPRECATED`- QoS profile is actively being used in a QoD session, but can not be deployed in new QoD sessions
      type: string
      enum:
        - ACTIVE
        - INACTIVE
        - DEPRECATED

    RateUnitEnum:
      description: Units of rate
      type: string
      enum:
        - bps
        - kbps
        - Mbps
        - Gbps
        - Tbps

    QosProfileDeviceRequest:
      description: |
        Request object for QoS Profiles for a given device
      type: object
      properties:
        device:
          $ref: "#/components/schemas/Device"
        name:
          $ref: "#/components/schemas/QosProfileName"
        status:
          $ref: '#/components/schemas/QosProfileStatusEnum'

    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`
        NOTE1: the network operator might support only a subset of these options. The API invoker can provide multiple identifiers to be compatible across different operators. 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
      maxProperties: 4

    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"

    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"

    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": "203.0.113.0",
          "publicPort": 59765
        }

    Port:
      description: TCP or UDP port number
      type: integer
      minimum: 0
      maximum: 65535

    SingleIpv4Addr:
      description: A single IPv4 address with no subnet mask
      type: string
      format: ipv4
      example: "203.0.113.0"

    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).

        The session shall apply to all IP flows between the device subnet and the specified application server, unless further restricted by the optional parameters devicePorts or applicationServerPorts.
      type: string
      format: ipv6
      example: 2001:db8:85a3:8d3:1319:8a2e:370:7344

    ErrorInfo:
      description: Common schema for errors
      type: object
      properties:
        status:
          type: integer
          description: HTTP status code returned along with this error response
        code:
          type: string
          description: Code given to this error
        message:
          type: string
          description: Detailed error description
      required:
        - status
        - code
        - message

  responses:
    Generic400:
      description: Bad Request
      headers:
        x-correlator:
          $ref: "#/components/headers/x-correlator"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
          examples:
            GENERIC_400_INVALID_ARGUMENT:
              description: Invalid Argument. Generic Syntax Exception
              value:
                status: 400
                code: INVALID_ARGUMENT
                message: Client specified an invalid argument, request body or query param.
            GENERIC_400_OUT_OF_RANGE:
              description: Out of Range. Specific Syntax Exception used when a given field has a pre-defined range or a invalid filter criteria combination is requested
              value:
                status: 400
                code: OUT_OF_RANGE
                message: Client specified an invalid range.

    Generic401:
      description: Unauthorized
      headers:
        x-correlator:
          $ref: "#/components/headers/x-correlator"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
          examples:
            GENERIC_401_UNAUTHENTICATED:
              description: Request cannot be authenticated
              value:
                status: 401
                code: UNAUTHENTICATED
                message: Request not authenticated due to missing, invalid, or expired credentials.
            GENERIC_401_AUTHENTICATION_REQUIRED:
              description: New authentication is needed, authentication is no longer valid
              value:
                status: 401
                code: AUTHENTICATION_REQUIRED
                message: New authentication is required.

    Generic403:
      description: Forbidden
      headers:
        x-correlator:
          $ref: "#/components/headers/x-correlator"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
          examples:
            GENERIC_403_PERMISSION_DENIED:
              description: Permission denied. OAuth2 token access does not have the required scope or when the user fails operational security
              value:
                status: 403
                code: PERMISSION_DENIED
                message: Client does not have sufficient permissions to perform this action.
            GENERIC_403_INVALID_TOKEN_CONTEXT:
              description: Reflect some inconsistency between information in some field of the API and the related OAuth2 Token
              value:
                status: 403
                code: INVALID_TOKEN_CONTEXT
                message: "{{field}} is not consistent with access token."

    Generic404:
      description: Not found
      headers:
        x-correlator:
          $ref: "#/components/headers/x-correlator"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
          examples:
            GENERIC_404_NOT_FOUND:
              description: Resource is not found
              value:
                status: 404
                code: NOT_FOUND
                message: The specified resource is not found.

    GenericDevice404:
      description: Not found
      headers:
        x-correlator:
          $ref: "#/components/headers/x-correlator"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
          examples:
            GENERIC_404_NOT_FOUND:
              description: Resource is not found
              value:
                status: 404
                code: NOT_FOUND
                message: The specified resource is not found.
            GENERIC_404_DEVICE_NOT_FOUND:
              description: Device identifier not found
              value:
                status: 404
                code: DEVICE_NOT_FOUND
                message: Device identifier not found.

    Generic422:
      description: Unprocessable Content
      headers:
        x-correlator:
          $ref: "#/components/headers/x-correlator"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
          examples:
            GENERIC_422_DEVICE_IDENTIFIERS_MISMATCH:
              description: Inconsistency between device identifiers not pointing to the same device
              value:
                status: 422
                code: DEVICE_IDENTIFIERS_MISMATCH
                message: Provided device identifiers are not consistent.
            GENERIC_422_DEVICE_NOT_APPLICABLE:
              description: Service is not available for the provided device
              value:
                status: 422
                code: DEVICE_NOT_APPLICABLE
                message: The service is not available for the provided device.
            GENERIC_422_UNIDENTIFIABLE_DEVICE:
              description: Service is not available for the provided device
              value:
                status: 422
                code: UNIDENTIFIABLE_DEVICE
                message: The device cannot be identified.

    Generic429:
      description: Too Many Requests
      headers:
        x-correlator:
          $ref: "#/components/headers/x-correlator"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
          examples:
            GENERIC_429_QUOTA_EXCEEDED:
              description: Request is rejected due to exceeding a business quota limit
              value:
                status: 429
                code: QUOTA_EXCEEDED
                message: Either out of resource quota or reaching rate limiting.
            GENERIC_429_TOO_MANY_REQUESTS:
              description: API Server request limit is overpassed
              value:
                status: 429
                code: TOO_MANY_REQUESTS
                message: Either out of resource quota or reaching rate limiting.

    Generic500:
      description: Internal server error
      headers:
        x-correlator:
          $ref: '#/components/headers/x-correlator'
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
          example:
            status: 500
            code: INTERNAL
            message: "Internal server error: ..."

    Generic503:
      description: Service Unavailable
      headers:
        x-correlator:
          $ref: "#/components/headers/x-correlator"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorInfo"
          examples:
            GENERIC_503_UNAVAILABLE:
              description: Service is not available. Temporary situation usually related to maintenance process in the server side
              value:
                status: 503
                code: UNAVAILABLE
                message: Service Unavailable.