GSMA Camara Project Application Profiles API

openapi: 3.0.3
info:
  title: Global System for Mobile Communications GSMA Camara Project Application Profiles API
  version: 0.3.0
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  description: >-
    Application profiles allows application developers to share all the
    information about their application which would be relevant for network/
    CAMARA APIs related decision making.
  x-camara-commonalities: 0.4.0
servers:
  - url: '{apiRoot}/application-profiles/v0.3'
    variables:
      apiRoot:
        default: http://localhost:9091
        description: |
          API root, defined by service provider, e.g.
          `api.example.com` or `api.example.com/somepath`
tags:
  - name: Application Profiles
    description: |
      Operations to define, read and manage an application's thresholds
      for network quality (latency, jitter, loss, throughput)
paths:
  /application-profiles:
    post:
      security:
        - openId:
            - application-profiles:create
      tags:
        - Application Profiles
      summary: |-
        Global System for Mobile Communications create a profile which represents an application's networking demands.
      description: |
        Define network monitoring intents for optimal end user application
        experience.
      operationId: createApplicationProfile
      requestBody:
        description: List of user-defined network quality thresholds
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApplicationProfileRequest'
        required: true
      responses:
        '201':
          description: Created
          headers:
            x-correlator:
              $ref: '#/components/headers/x-correlator'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationProfile'
        '400':
          $ref: '#/components/responses/Generic400'
        '401':
          $ref: '#/components/responses/Generic401'
        '403':
          $ref: '#/components/responses/Generic403'
        '500':
          $ref: '#/components/responses/Generic500'
        '503':
          $ref: '#/components/responses/Generic503'
  /application-profiles/{applicationProfileId}:
    patch:
      security:
        - openId:
            - application-profiles:update
      tags:
        - Application Profiles
      description: |
        Update the complete set of network quality thresholds for an
        application with the new set of thresholds to ensure good
        end user experience
      operationId: updateApplicationProfile
      parameters:
        - name: applicationProfileId
          in: path
          description: Identifier for the Application Profile
          required: true
          style: simple
          explode: false
          schema:
            type: string
            format: uuid
      requestBody:
        description: |
          network monitoring intents for optimal end user application
          experience.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApplicationProfile'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationProfile'
        '400':
          $ref: '#/components/responses/Generic400'
        '401':
          $ref: '#/components/responses/Generic401'
        '403':
          $ref: '#/components/responses/Generic403'
        '404':
          $ref: '#/components/responses/Generic404'
        '500':
          $ref: '#/components/responses/Generic500'
        '503':
          $ref: '#/components/responses/Generic503'
    get:
      security:
        - openId:
            - application-profiles:read
      tags:
        - Application Profiles
      description: Read an Application Profile
      operationId: readApplicationProfile
      parameters:
        - name: applicationProfileId
          in: path
          description: Identifier for the Application Profile
          required: true
          style: simple
          explode: false
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationProfile'
        '400':
          $ref: '#/components/responses/Generic400'
        '401':
          $ref: '#/components/responses/Generic401'
        '403':
          $ref: '#/components/responses/Generic403'
        '404':
          $ref: '#/components/responses/Generic404'
        '500':
          $ref: '#/components/responses/Generic500'
        '503':
          $ref: '#/components/responses/Generic503'
    delete:
      security:
        - openId:
            - application-profile:delete
      tags:
        - Application Profiles
      description: delete
      operationId: deleteApplicationProfile
      parameters:
        - name: applicationProfileId
          in: path
          description: subscription Id
          required: true
          style: simple
          explode: false
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: application profile has been deleted
        '400':
          $ref: '#/components/responses/Generic400'
        '401':
          $ref: '#/components/responses/Generic401'
        '403':
          $ref: '#/components/responses/Generic403'
        '404':
          $ref: '#/components/responses/Generic404'
        '500':
          $ref: '#/components/responses/Generic500'
        '503':
          $ref: '#/components/responses/Generic503'
components:
  securitySchemes:
    openId:
      description: OpenID Provider Configuration Information
      type: openIdConnect
      openIdConnectUrl: https://example.com/.well-known/openid-configuration
  headers:
    x-correlator:
      description: Correlation id for the different services
      schema:
        type: string
  schemas:
    Duration:
      type: object
      properties:
        value:
          type: integer
          example: 12
          format: int32
          minimum: 1
        unit:
          allOf:
            - $ref: '#/components/schemas/TimeUnitEnum'
            - example: Minutes
    TimeUnitEnum:
      type: string
      enum:
        - Days
        - Hours
        - Minutes
        - Seconds
        - Milliseconds
        - Microseconds
        - Nanoseconds
    Rate:
      type: object
      properties:
        value:
          type: integer
          example: 10
          format: int32
          minimum: 0
          maximum: 1024
        unit:
          $ref: '#/components/schemas/RateUnitEnum'
    RateUnitEnum:
      type: string
      enum:
        - bps
        - kbps
        - Mbps
        - Gbps
        - Tbps
    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'
    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
    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'
    targetMinDownstreamRate:
      description: |
        This is the target minimum downstream rate.
      allOf:
        - $ref: '#/components/schemas/Rate'
    targetMinUpstreamRate:
      description: |
        This is the target minimum upstream rate.
      allOf:
        - $ref: '#/components/schemas/Rate'
    ApplicationProfile:
      type: object
      required:
        - applicationProfileId
        - networkQualityThresholds
      properties:
        applicationProfileId:
          type: string
          format: uuid
        networkQualityThresholds:
          $ref: '#/components/schemas/NetworkQualityThresholds'
    ApplicationProfileRequest:
      type: object
      required:
        - networkQualityThresholds
      properties:
        networkQualityThresholds:
          $ref: '#/components/schemas/NetworkQualityThresholds'
    NetworkQualityThresholds:
      type: object
      properties:
        packetDelayBudget:
          $ref: '#/components/schemas/packetDelayBudget'
        targetMinDownstreamRate:
          $ref: '#/components/schemas/targetMinDownstreamRate'
        targetMinUpstreamRate:
          $ref: '#/components/schemas/targetMinUpstreamRate'
        packetlossErrorRate:
          $ref: '#/components/schemas/packetErrorLossRate'
        jitter:
          $ref: '#/components/schemas/jitter'
    ErrorInfo:
      type: object
      description: Error information
      required:
        - status
        - code
        - message
      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
  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.
            GENERIC_404_DEVICE_NOT_FOUND:
              description: Device identifier not found
              value:
                status: 404
                code: DEVICE_NOT_FOUND
                message: Device identifier not found.
    Generic500:
      description: Internal Server Error
      headers:
        x-correlator:
          $ref: '#/components/headers/x-correlator'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          examples:
            GENERIC_500_INTERNAL:
              description: Problem in Server side. Regular Server Exception
              value:
                status: 500
                code: INTERNAL
                message: Unknown server error. Typically a server bug.
    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.