GSMA Camara Project Edge Application Management API

openapi: 3.0.3
info:
  title: Global System for Mobile Communications GSMA Camara Project Edge Application Management API
  version: 0.9.3-wip
  description: >-
    Edge Application Management API allows API consumers to manage the Life
    Cycle of an Application and to Discover Edge Cloud Zones. The reference
    scenario foresees a distributed Telco Edge Cloud where any Application
    Delevoper, known as an Application Provider, can host and deploy their
    application according to their specifications and operational criteria (e.g.
    within an specific geographical zone for data protection

    purposes, ensure a minimum QoS for the application clients, etc).
  contact:
    email: [email protected]
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
externalDocs:
  description: Product documentation at Camara
  url: https://github.com/camaraproject/EdgeCloud
servers:
  - url: '{apiRoot}/{basePath}'
    variables:
      apiRoot:
        default: http://localhost:443
        description: API root
      basePath:
        default: edge-application-management/vwip
        description: Base path for the Edge Application Management API
tags:
  - name: Application
    description: Application and Application Instance Lice Cycle Management
  - name: Edge Cloud
    description: Edge Cloud Zones Availability
paths:
  /apps:
    post:
      security:
        - openId:
            - edge-application-management:apps:write
      tags:
        - Application
      summary: Global System for Mobile Communications Submit application metadata to the Edge Cloud Provider.
      description: |
        Contains the information about the application to be
        instantiated in the Edge Cloud
      operationId: submitApp
      parameters:
        - $ref: '#/components/parameters/x-correlator'
      requestBody:
        description: |
          The Application Provider request contains mandatory
          criteria (e.g. required CPU, memory, storage, bandwidth) and
          optional parameters.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AppManifest'
        required: true
      responses:
        '201':
          description: Application created successfully
          headers:
            x-correlator:
              $ref: '#/components/headers/x-correlator'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmittedApp'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              example:
                status: 409
                code: CONFLICT
                message: App already exists
        '500':
          $ref: '#/components/responses/500'
        '501':
          $ref: '#/components/responses/501'
        '503':
          $ref: '#/components/responses/503'
    get:
      security:
        - openId:
            - edge-application-management:apps:read
      tags:
        - Application
      summary: Global System for Mobile Communications Retrieve a list of existing Applications
      description: |
        Get the list of all existing Application definitions from the
        Edge Cloud Provider that the user has permission to view.
      operationId: getApps
      parameters:
        - $ref: '#/components/parameters/x-correlator'
      responses:
        '200':
          description: List of existing applications
          headers:
            x-correlator:
              $ref: '#/components/headers/x-correlator'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AppManifest'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
        '503':
          $ref: '#/components/responses/503'
  /apps/{appId}:
    get:
      security:
        - openId:
            - edge-application-management:apps:read
      tags:
        - Application
      summary: Global System for Mobile Communications Retrieve the information of an Application
      description: |
        Ask the Edge Cloud Provider the information for a given application
      operationId: getApp
      parameters:
        - $ref: '#/components/parameters/x-correlator'
        - name: appId
          description: |
            A globally unique identifier associated with the
            application.
            Edge Cloud Provider generates this identifier when the application
            is submitted.
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/AppId'
      responses:
        '200':
          description: Information of Application
          headers:
            x-correlator:
              $ref: '#/components/headers/x-correlator'
          content:
            application/json:
              schema:
                type: object
                properties:
                  appManifest:
                    $ref: '#/components/schemas/AppManifest'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
        '503':
          $ref: '#/components/responses/503'
    delete:
      security:
        - openId:
            - edge-application-management:apps:delete
      tags:
        - Application
      summary: |-
        Global System for Mobile Communications Delete an Application from an Edge Cloud Provider
      description: Delete all the information and content related to an Application
      operationId: deleteApp
      parameters:
        - $ref: '#/components/parameters/x-correlator'
        - name: appId
          in: path
          description: |
            Identificator of the application to be
            deleted provided by the Edge Cloud Provider
            once the submission was successful
          required: true
          schema:
            $ref: '#/components/schemas/AppId'
      responses:
        '202':
          description: Request accepted
          headers:
            x-correlator:
              $ref: '#/components/headers/x-correlator'
        '204':
          description: App deleted
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              example:
                status: 409
                code: CONFLICT
                message: App with a running application instance cannot be deleted
        '500':
          $ref: '#/components/responses/500'
        '503':
          $ref: '#/components/responses/503'
  /appinstances:
    post:
      security:
        - openId:
            - edge-application-management:instances:write
      tags:
        - Application
      summary: Global System for Mobile Communications Instantiation of an Application
      description: |
        Ask the Edge Cloud Platform to instantiate an application to one
        or several Edge Cloud Zones with an Application as an input and an
        Application Instance as the output.
      operationId: createAppInstance
      parameters:
        - $ref: '#/components/parameters/x-correlator'
      requestBody:
        description: |
          The Application ID and the array of Edge Cloud Zones to deploy
          it to.
        content:
          application/json:
            schema:
              type: object
              required:
                - appId
                - appZones
              properties:
                appId:
                  $ref: '#/components/schemas/AppId'
                appZones:
                  $ref: '#/components/schemas/AppZones'
        required: true
      responses:
        '202':
          description: Application instantiation accepted
          headers:
            x-correlator:
              $ref: '#/components/headers/x-correlator'
            Location:
              description: Contains the URI of the newly created application.
              required: true
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  appInstances:
                    type: array
                    items:
                      $ref: '#/components/schemas/AppInstanceInfo'
                minItems: 1
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              example:
                status: 409
                code: CONFLICT
                message: >-
                  Application already instantiated in the given Edge Cloud Zone
                  or Edge Cloud Region
        '500':
          $ref: '#/components/responses/500'
        '501':
          $ref: '#/components/responses/501'
        '503':
          $ref: '#/components/responses/503'
    get:
      security:
        - openId:
            - edge-application-management:instances:read
      tags:
        - Application
      summary: Global System for Mobile Communications Retrieve the information of Application Instances for a given App
      description: |
        Ask the Edge Cloud Provider the information of the instances for a
        given application
      operationId: getAppInstance
      parameters:
        - $ref: '#/components/parameters/x-correlator'
        - name: appId
          description: |
            A globally unique identifier associated with
            the application.
            Edge Cloud Provider generates this identifier when the
            application is submitted.
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/AppId'
        - name: appInstanceId
          description: |
            A globally unique identifier associated with a running
            instance of an application within an specific Edge Cloud Zone.
            Edge Cloud Provider generates this identifier.
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/AppInstanceId'
        - name: region
          description: |
            Human readable name of the geographical Edge Cloud Region of
            the Edge Cloud. Defined by the Edge Cloud Provider.
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/EdgeCloudRegion'
      responses:
        '200':
          description: Information of Application Instances
          headers:
            x-correlator:
              $ref: '#/components/headers/x-correlator'
          content:
            application/json:
              schema:
                type: object
                properties:
                  appInstanceInfo:
                    type: array
                    items:
                      $ref: '#/components/schemas/AppInstanceInfo'
                minItems: 1
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
        '503':
          $ref: '#/components/responses/503'
  /appinstances/{appInstanceId}:
    delete:
      security:
        - openId:
            - edge-application-management:instances:delete
      tags:
        - Application
      summary: Global System for Mobile Communications Terminate an Application Instance
      description: |
        Terminate a running instance of an application within
        an Edge Cloud Zone
      operationId: deleteAppInstance
      parameters:
        - $ref: '#/components/parameters/x-correlator'
        - name: appInstanceId
          in: path
          description: |
            Identificator of the specific application instance
            that will be terminated
          required: true
          schema:
            $ref: '#/components/schemas/AppInstanceId'
      responses:
        '202':
          description: |
            Request accepted to be processed. It applies for async
            deletion process
          headers:
            x-correlator:
              $ref: '#/components/headers/x-correlator'
        '204':
          description: Application Instance Deleted
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
        '503':
          $ref: '#/components/responses/503'
  /edge-cloud-zones:
    get:
      security:
        - openId:
            - edge-application-management:edge-cloud-zones:read
      tags:
        - Edge Cloud
      summary: Global System for Mobile Communications Retrieve a list of the operators Edge Cloud Zones and their status
      description: |
        List of the operators Edge Cloud Zones and their
        status, ordering the results by location and filtering by
        status (active/inactive/unknown)
      operationId: getEdgeCloudZones
      parameters:
        - $ref: '#/components/parameters/x-correlator'
        - name: region
          description: |
            Human readable name of the geographical Edge Cloud Region of
            the Edge Cloud. Defined by the Edge Cloud Provider.
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/EdgeCloudRegion'
        - name: status
          description: Human readable status of the Edge Cloud Zone
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/EdgeCloudZoneStatus'
      responses:
        '200':
          description: |
            Successful response, returning the
            Available Edge Cloud Zones.
          headers:
            x-correlator:
              $ref: '#/components/headers/x-correlator'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EdgeCloudZones'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
        '503':
          $ref: '#/components/responses/503'
components:
  securitySchemes:
    openId:
      description: OpenID Provider Configuration Information.
      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
      required: false
      schema:
        type: string
        format: uuid
  schemas:
    AccessEndpoint:
      type: object
      description: |
        Application Endpoint for an especific instance that is
        running in an specific Edge Cloud Zone.
      required:
        - port
      anyOf:
        - required:
            - fqdn
        - required:
            - ipv4Addresses
        - required:
            - ipv6Addresses
      properties:
        port:
          $ref: '#/components/schemas/Port'
        fqdn:
          $ref: '#/components/schemas/Fqdn'
        ipv4Addresses:
          description: IP version 4 of an application instance
          type: array
          items:
            $ref: '#/components/schemas/Ipv4Addr'
          minItems: 1
        ipv6Addresses:
          description: IP version 6 of an application instance.
          type: array
          items:
            $ref: '#/components/schemas/Ipv6Addr'
          minItems: 1
    AppId:
      type: string
      format: uuid
      description: |
        A globally unique identifier associated with the application.
        Edge Cloud Platform generates this identifier when the
        Application is submitted.
    AppInstanceId:
      type: string
      format: uuid
      description: |
        A globally unique identifier associated with a running
        instance of an application.
        Edge Cloud Platform generates this identifier when the
        instantiation in the Edge Cloud Zone is successful.
    AppInstanceInfo:
      description: Information about the application instance.
      type: object
      properties:
        appInstanceId:
          $ref: '#/components/schemas/AppInstanceId'
        status:
          description: Status of the application instance (default is 'unknown')
          type: string
          enum:
            - ready
            - instantiating
            - failed
            - terminating
            - unknown
          default: unknown
        componentEndpointInfo:
          description: |
            Information about the IP and Port exposed by the
            Edge Cloud Platform.
            Application Client shall use these access points to reach this
            application instance
          type: array
          items:
            type: object
            required:
              - interfaceId
              - accessPoints
            properties:
              interfaceId:
                type: string
                pattern: ^[A-Za-z0-9][A-Za-z0-9_]{6,30}[A-Za-z0-9]$
                description: |
                  This is the interface Identifier that Application Provider
                  defines when application is being submitted.
              accessPoints:
                $ref: '#/components/schemas/AccessEndpoint'
          minItems: 1
        kubernetesClusterRef:
          $ref: '#/components/schemas/KubernetesClusterRef'
        edgeCloudZone:
          $ref: '#/components/schemas/EdgeCloudZone'
    AppZones:
      description: |
        Collection of Edge Cloud Zones and/or Kubernetes cluster reference
        where the Application Provider wants to instantiate the application.
      type: array
      items:
        type: object
        properties:
          kubernetesClusterRef:
            $ref: '#/components/schemas/KubernetesClusterRef'
          EdgeCloudZone:
            $ref: '#/components/schemas/EdgeCloudZone'
      required:
        - EdgeCloudZone
      minItems: 1
      additionalProperties: false
    AppManifest:
      description: |
        Application information and requirements provided by the
        Application Provider
      properties:
        appId:
          $ref: '#/components/schemas/AppId'
        name:
          type: string
          pattern: ^[A-Za-z][A-Za-z0-9_]{1,63}$
          description: Name of the application.
        appProvider:
          $ref: '#/components/schemas/AppProvider'
        version:
          type: string
          description: Application version information
        packageType:
          description: Format of the application image package
          type: string
          enum:
            - QCOW2
            - OVA
            - CONTAINER
            - HELM
        operatingSystem:
          $ref: '#/components/schemas/OperatingSystem'
        appRepo:
          description: |
            Repository where Application Provider stores the application image
          type: object
          required:
            - type
            - imagePath
          properties:
            type:
              type: string
              enum:
                - PRIVATEREPO
                - PUBLICREPO
              description: |
                Application repository and image URI information.
                PUBLICREPO is used of public urls like github, helm repo etc.
                PRIVATEREPO  is used for private repo managed by the application
                developer. Private repo can be accessed by using the app
                developer provided userName and password. Password is
                recommended to be the personal access token created by developer
                e.g. in Github repo.
            imagePath:
              $ref: '#/components/schemas/Uri'
            userName:
              type: string
              description: |
                Username to acces the Helm chart, docker-compose
                file or VM image repository
            credentials:
              type: string
              maxLength: 128
              description: |
                Password or personal access token created by
                developer to acces the app repository. API users can generate
                a personal access token e.g. docker clients to use them as
                password.
            authType:
              type: string
              enum:
                - DOCKER
                - HTTP_BASIC
                - HTTP_BEARER
                - NONE
              description: |
                The credentials can also be formatted as a Basic
                auth or Bearer auth in HTTP "Authorization" header.
            checksum:
              type: string
              description: |
                MD5 checksum for VM and file-based images, sha256
                digest for containers
        requiredResources:
          $ref: '#/components/schemas/RequiredResources'
        componentSpec:
          description: |
            Information defined in "appRepo" point to the application
            descriptor e.g. Helm chart, docker-compose yaml file etc.
            The descriptor may contain one or more containers and their
            associated meta-data. A component refers to additional details
            about these containers to expose the instances of the containers
            to external client applications. App provider can define one or
            more components (via the associated network port) in componentSpec
            corresponding to the containers in helm charts or docker-compose
            yaml file as part of app descriptors.
          type: array
          items:
            type: object
            required:
              - componentName
              - networkInterfaces
            properties:
              componentName:
                type: string
                description: Component name must be unique with an application
              networkInterfaces:
                description: |
                  Each application component exposes some ports
                  either for external users or for inter component
                  communication.
                  Application provider is required to specify which ports are
                  to be exposed and the type of traffic that will flow through
                  these ports.The underlying platform may assign a dynamic port
                  against the "extPort" that the application clients will use
                  to connect with edge application instance.
                type: array
                items:
                  type: object
                  required:
                    - interfaceId
                    - protocol
                    - port
                    - visibilityType
                  properties:
                    interfaceId:
                      type: string
                      pattern: ^[A-Za-z][A-Za-z0-9_]{3,31}$
                      description: |
                        Each Port and corresponding traffic protocol
                        exposed by the component is identified by a name.
                        Application client on user device requires this to
                        uniquley idenify the interface.
                    protocol:
                      type: string
                      enum:
                        - TCP
                        - UDP
                        - ANY
                      description: |
                        Defines the IP transport communication
                        protocol i.e., TCP, UDP or ANY
                    port:
                      type: integer
                      format: int32
                      minimum: 1
                      maximum: 65535
                      description: |
                        Port number exposed by the component.
                        Edge Cloud Provider may generate a dynamic port
                        towards the component instance which forwards
                        external traffic to the component port.
                    visibilityType:
                      description: |
                        Defines whether the interface is exposed
                        to outer world or not i.e., external, or internal.
                        If this is set to "external", then it is  exposed
                        to external applications otherwise it is exposed
                        internally to edge application components within
                        edge cloud. When exposed to external world,
                        an external dynamic port is assigned for UC traffic
                        and mapped to the extPort
                      type: string
                      enum:
                        - VISIBILITY_EXTERNAL
                        - VISIBILITY_INTERNAL
                minItems: 1
      required:
        - name
        - version
        - appProvider
        - packageType
        - appRepo
        - requiredResources
        - componentSpec
    AppProvider:
      type: string
      pattern: ^[A-Za-z][A-Za-z0-9_]{7,63}$
      description: Human readable name of the Application Provider.
    EdgeCloudProvider:
      type: string
      description: Human readable name of the Edge Cloud Provider.
    EdgeCloudRegion:
      type: string
      description: |
        Human readable name of the geographical Edge Cloud Region of
        the Edge Cloud. Defined by the Edge Cloud Provider.
    EdgeCloudZones:
      type: array
      items:
        $ref: '#/components/schemas/EdgeCloudZone'
      minItems: 1
      description: |
        A collection of Edge Cloud Zones where the Application Provider can
        instantiate an Application Instance.
      additionalProperties: false
    EdgeCloudZoneId:
      type: string
      format: uuid
      description: |
        Unique identifier created by the Edge Cloud Platform to identify an
        Edge Cloud Zone within an Edge Cloud.
    EdgeCloudZone:
      type: object
      description: |
        An Edge Cloud Zone, uniquely identified by a
        combination of the value of the Edge Cloud Zone Id object
        and the value of the Edge Cloud Provider
        object. This value is used to identify an Edge Cloud zone
        between Edge Clouds from different Edge Cloud Providers.
      required:
        - edgeCloudZoneId
        - edgeCloudZoneName
        - edgeCloudProvider
      properties:
        edgeCloudZoneId:
          $ref: '#/components/schemas/EdgeCloudZoneId'
        edgeCloudZoneName:
          $ref: '#/components/schemas/EdgeCloudZoneName'
        edgeCloudZoneStatus:
          $ref: '#/components/schemas/EdgeCloudZoneStatus'
        edgeCloudProvider:
          $ref: '#/components/schemas/EdgeCloudProvider'
        edgeCloudRegion:
          $ref: '#/components/schemas/EdgeCloudRegion'
      minItems: 1
    EdgeCloudZoneName:
      type: string
      description: |
        Human readable name of the geographical zone of
        the Edge Cloud. Defined by the Edge Cloud Provider.
    EdgeCloudZoneStatus:
      description: Status of the Edge Cloud Zone (default is 'unknown')
      type: string
      enum:
        - active
        - inactive
        - unknown
      default: unknown
    ErrorInfo:
      type: object
      description: Information about the error
      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
    Fqdn:
      type: string
      description: |
        Full qualified domain name of an application instance
    GpuInfo:
      type: object
      description: Information about the supported GPUs
      required:
        - gpuMemory
        - numGPU
      properties:
        gpuMemory:
          type: integer
          description: GPU memory in mega bytes
        numGPU:
          type: integer
          description: Number of GPUs
    K8sAddons:
      description: |
        Addons for the Kubernetes cluster.
        Additional addons should be defined in application the helm chart
        (Service Mesh, Serverless, AI).
      type: object
      properties:
        monitoring:
          type: boolean
          example: true
          default: false
          description: Enable monitoring for Kubernetes cluster.
        ingress:
          type: boolean
          example: true
          default: false
          description: Enable ingress for Kubernetes cluster.
    K8sNetworking:
      description: |
        Kubernetes networking definition
      type: object
      properties:
        primaryNetwork:
          description: Definition of Kubernetes primary Network
          type: object
          properties:
            provider:
              description: CNI provider name
              type: string
              example: cilium
            version:
              description: CNI provider version
              type: string
              example: '1.13'
        additionalNetworks:
          description: Additional Networks for the Kubernetes cluster.
          type: array
          items:
            type: object
            description: Additional network interface definition
            properties:
              name:
                description: Additional Network Name
                type: string
                example: net1
              interfaceType:
                description: |
                  Type of additional Interface:
                  netdevice: (SR-IOV) A regular kernel network device in the
                             Network Namespace (netns) of the container
                  vfio-pci: (SR-IOV) A PCI network interface directly mounted
                            in the container
                  interface: Additional interface to be used by cni plugins
                             such as macvlan, ipvlan
                  Note: The use of SR-IOV interfaces automatically
                  configure the required kernel parameters for the nodes.
                type: string
                example: vfio-pci
                enum:
                  - netdevice
                  - vfio-pci
                  - interface
    AdditionalStorage:
      description: Additional storage for the application.
      type: array
      items:
        type: object
        required:
          - storageSize
          - mountPoint
        properties:
          name:
            type: string
            description: Name of additional storage resource.
            example: logs
          storageSize:
            type: string
            description: Additional persistent volume for the application.
            example: 80GB
            pattern: ^\d+(GB|MB)$
          mountPoint:
            type: string
            description: Location of additional storage resource.
            example: /logs
    Vcpu:
      type: string
      pattern: ^\d+((\.\d{1,3})|(m))?$
      description: |
        Number of vcpus in whole (i.e 1), decimal (i.e 0.500) up to
        millivcpu, or millivcpu (i.e 500m) format

# --- truncated at 32 KB (45 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/global-system-for-mobile-communications/refs/heads/main/openapi/edge-application-management-api-openapi.yml