Global System for Mobile Communications Application Profiles API

openapi: 3.0.3
info:
  title: Global System for Mobile Communications GSMA Camara Project Endpoint Discovery Application Application Profiles API
  version: 0.1.0-wip
  description: The Application Discovery API extends beyond the capabilities of the Simple Edge Discovery API by not only locating the nearest Edge Cloud Zone but also directly linking to the application endpoints within those Edge Cloud Zones.
  contact:
    email: sp-edc@lists.camaraproject.org
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: '{apiRoot}/{basePath}'
  variables:
    apiRoot:
      default: https://localhost:443
      description: API root.
    basePath:
      default: application-endpoint-discovery/vwip
      description: Base path for the Application Endpoint Discovery.
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:
  responses:
    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.
    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.
    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.
  schemas:
    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'
    RateUnitEnum:
      type: string
      enum:
      - bps
      - kbps
      - Mbps
      - Gbps
      - Tbps
    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
    ApplicationProfileRequest:
      type: object
      required:
      - networkQualityThresholds
      properties:
        networkQualityThresholds:
          $ref: '#/components/schemas/NetworkQualityThresholds'
    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'
    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
    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'
  headers:
    x-correlator:
      description: Correlation id for the different services
      schema:
        type: string
  securitySchemes:
    openId:
      description: OpenID Provider Configuration Information.
      type: openIdConnect
      openIdConnectUrl: .well-known/openid-configuration
externalDocs:
  description: Product documentation at CAMARA.
  url: https://github.com/camaraproject/EdgeCloud