---
openapi: 3.0.3
info:
title: Open Exposure Gateway API
version: 1.0.1-wip
description: |
Open Exposure Gateway API allows API consumers to manage the
Life Cycle of an Application, Discover Edge Cloud Zones and request Network Resources.
# Overview
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).
Through Telco Edge Cloud services Developers around the globe can be
benefit from the traditional Cloud strengths but expertise and advantages
of the Mobile Network Operators offering to their users an evolved
experience for XR, V2X, Holographic and other new services.
# Introduction
The Edge Application Management API provides capabilities for lifecycle
management of application, instances and edge cloud zone discovery.
Lifecycle Management allows Application Provider to onboard
their application to the Edge Cloud Platform which do bookkeeping,
resource validation and other pre-deployment operations.
Application details can contain components network specification,
package type (QCOW2, OVA, CONTAINER, HELM), operating system details and
respository to download the image of the desired application.
Once the application is available on the Edge Cloud
Platform, the Application Provider can instantiate the application.
Edge Cloud Provider helps Application Provider to decide where to
instantiate the applications allowing them to retrieve a list of
Edge Cloud Zones that meets the provided criteria.
This discovery can be filtered by an specific geographical region
(e.g when data residency is need) and by status (active, inactive, unknown)
Application Provider can ask the Edge Cloud Platform to instantiate the
application to one or several Edge Cloud Zones that meet the criteria.
Typically when more than one Edge Cloud Zone is required in the same
geographic boundary, Application Provider can define instead
the entire Edge Cloud Region.
Application Provider can retrieve the information of the instances
for a given application, the information could be the Edge Cloud Zone
where the instance is, status (ready, instantiating, failed,
terminating, unknown) and endpoint (ip, port, fqdn).
Application Provider can terminate an instance of an application
(appInstanceId) or all the instances for a given appId.
# Quick Start
The usage of this API is based on several resources including GSMA
Edge Platform, Public Cloud and SDOs, to define a first approach on the
lifecycle management of application instances and edge cloud zones discovery
Before starting to use the API, the developer needs to know about
the below specified details.
__Application Management__
* __submitApp__ - Submits application details to an Edge Cloud Provider.
Based on the details provided, Edge Cloud Provider shall do bookkeeping,
resource validation and other pre-deployment operations.
* __deleteApp__ - Removes an application from an Edge Cloud Provider,
if there is a running instance of the given application,
the request cannot be done.
* __getApp__ - Retrieves the information of a given application.
__Application Instance Management__
* __createAppInstance__ Request the Edge Cloud Provider to instatiate
an instance of an application in a given Edge Cloud Zone,
if this parameter is not set, the Edge Cloud Provider will instantiate
the applications in all the Edge Cloud Zones.
* __getAppInstance__ Retrieves the list with information of the instances
related to a given application.
* __deleteAppInstance__ - Removes a given application instance from an Edge
Cloud Zone.
__Edge Cloud information__
* __getEdgeCloudZones__ List of the operators Edge Cloud Zones and their
status, ordering the results by location and filtering by status
(active/inactive/unknown)
# Authentication and Authorization
CAMARA guidelines defines a set of authorization flows which can grant API
clients access to the API functionality, as outlined in the document
[CAMARA-API-access-and-user-consent.md](https://github.com/camaraproject\
/IdentityAndConsentManagement/blob/main/documentation/CAMARA-API-access\
-and-user-consent.md).
Which specific authorization flows are to be used will be determined during
onboarding process, happening between the API Client and the Telco Edge
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.
# API documentation
Two operations have been defined in Edge Application Management API.
*__Application__* - The Application Provider submit application metadata to
the Edge Cloud Platform. The Edge Cloud Platform generates an appId for that
metadata that will be used to instantiate the application within
the Edge Cloud Zone.
*__Edge Cloud__* - Retrieves all the Edge Cloud Zones available according to
some defined parameters where an application can be instantiated.
Definitions of terminologies commonly referred
to throughout the API descriptions.
* __Application Provider__ - The provider of the application that accesses
an Edge Cloud Provider to deploy its application on the Edge Cloud.
An Application Provider may be part of a larger organisation,
like an enterprise, enterprise customer of an Edge Cloud Provider,
or be an independent entity.
* __Application__ - Contains the information about the application to be
instantiated. Descriptor, binary image, charts or any other package
assosiated with the application. The Application Provider request contains
mandatory criteria (e.g. required CPU, memory, storage, bandwidth) defined
in an Application. The Edge Cloud Platform generates a unique ID
for an Application that is ready to be instantiated.
* __Application Instance__ - Is an instance (VM or Container based) running
in an Edge Cloud Zone. The Edge Cloud Platform generates a unique ID
for each instance.
* __Edge Cloud__ - Cloud-like capabilities located at the network edge
including, from the Application Provider's perspective, access to
elastically allocated compute, data storage and network resources,
this access is provided through the Edge Cloud Platform.
* __Edge Cloud Provider__ - Company name of the provider offering the
Edge Services through the Edge Cloud Platform.
Could be an Operator or a Cloud Provider.
* __Edge Cloud Region__ - An Edge Cloud Region is equivalent
to a Region on a Public Cloud.
The higher construct in the hierarchy exposed to an Application
Provider who wishes to deploy an Application on the Edge Cloud and broadly
represents a geography. An Edge CloudRegion typically contains one or
multiple Edge Cloud Zones.
An Edge Cloud Region exists within an Edge Cloud.
* __Edge Cloud Zone__ - An Edge Cloud Zone is the lowest level of
abstraction exposed to an Application Provider who wants to deploy
an Application on Edge Cloud.
Edge Cloud Zones exists within a Edge Cloud Region.
---
contact:
email: sp-edc@lists.camaraproject.org
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
externalDocs:
description: Product documentation at Camara0
url: https://github.com/camaraproject/EdgeCloud
servers:
- url: http://vitrualserver:8080/oeg/1.0.0
paths:
/apps:
post:
# security:
# - openId:
# - edge-application-management:apps:write
tags:
- Application
summary: Submit application metadata to the Edge Cloud Provider.
description: |
Contains the information about the application to be
instantiated in the Edge Cloud
operationId: edge_cloud_management_api.controllers.app_controllers.submit_app
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"
examples:
KubernetesExample:
summary: Example for Kubernetes app
value:
appId: 3fa85f64-5717-4562-b3fc-2c963f66afa6
name: nginx_web_app
appProvider: nginx_inc
version: 1.0.0
packageType: HELM
operatingSystem:
architecture: x86_64
family: UBUNTU
version: OS_VERSION_UBUNTU_2204_LTS
license: OS_LICENSE_TYPE_FREE
appRepo:
type: PRIVATEREPO
imagePath: "https://charts.bitnami.com/bitnami/nginx:1.25.2"
userName: helm-user
credentials: secure-token
authType: DOCKER
checksum: sha256:4d67e4c1a4b4c8...
requiredResources:
infraKind: kubernetes
applicationResources:
cpuPool:
numCPU: 2
memory: 4096
topology:
minNumberOfNodes: 3
minNodeCpu: 2
minNodeMemory: 4096
gpuPool:
numCPU: 4
memory: 8192
gpuMemory: 32
topology:
minNumberOfNodes: 2
minNodeCpu: 4
minNodeMemory: 8192
minNodeGpuMemory: 16
isStandalone: false
version: "1.29"
additionalStorage: 100GB
networking:
primaryNetwork:
provider: cilium
version: "1.13"
additionalNetworks:
- name: net1
interfaceType: vfio-pci
- name: backend-net
interfaceType: netdevice
- name: db-net
interfaceType: interface
addons:
monitoring: true
ingress: true
componentSpec:
- componentName: nginx_server
networkInterfaces:
- interfaceId: eth0
protocol: TCP
port: 80
visibilityType: VISIBILITY_EXTERNAL
- interfaceId: eth1
protocol: TCP
port: 443
visibilityType: VISIBILITY_EXTERNAL
required: true
responses:
"200":
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: 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: edge_cloud_management_api.controllers.app_controllers.get_apps
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: Retrieve the information of an Application
description: |
Ask the Edge Cloud Provider the information for a given application
operationId: edge_cloud_management_api.controllers.app_controllers.get_app
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: |
Delete an Application from an Edge Cloud Provider
description: Delete all the information and content
related to an Application
operationId: edge_cloud_management_api.controllers.app_controllers.delete_app
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:
"200":
description: App deleted
"202":
description: Request accepted
headers:
x-correlator:
$ref: "#/components/headers/x-correlator"
"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: 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: edge_cloud_management_api.controllers.app_controllers.create_app_instance
parameters:
- $ref: "#/components/parameters/x-correlator"
requestBody:
description: |
Information about the application and where to deploy it.
content:
application/json:
schema:
type: object
required:
# - name
- appId
- appZones
# - edgeCloudZoneId
properties:
# name:
# $ref: '#/components/schemas/AppInstanceName'
appId:
$ref: "#/components/schemas/AppId"
# edgeCloudZoneId:
# $ref: "#/components/schemas/EdgeCloudZoneId"
# kubernetesClusterRef:
# $ref: "#/components/schemas/KubernetesClusterRef"
appZones:
$ref: "#/components/schemas/EdgeCloudZones"
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: 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: edge_cloud_management_api.controllers.app_controllers.get_app_instance
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: Terminate an Application Instance
description: |
Terminate a running instance of an application within
an Edge Cloud Zone
operationId: edge_cloud_management_api.controllers.app_controllers.delete_app_instance
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 Zones
summary: 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: edge_cloud_management_api.controllers.edge_cloud_controller.get_edge_cloud_zones
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"
/edge-cloud-zones/{zoneId}:
get:
tags:
- Edge Cloud Zones
summary: Retrieve the details of an Edge Cloud Zone
description: |
List of the operators Edge Cloud Zones and their
status, ordering the results by location and filtering by
status (active/inactive/unknown)
operationId: edge_cloud_management_api.controllers.edge_cloud_controller.edge_cloud_zone_details
parameters:
- $ref: "#/components/parameters/x-correlator"
- name: zoneId
in: path
description: |
UID of the specific edge cloud zone
required: true
style: simple
schema:
type: string
responses:
"200":
description: |
Successful response, returning the Edge Cloud Zone details
"404":
$ref: "#/components/responses/404"
/sessions:
post:
tags:
- Quality on Demand Functions
summary: Creates a new QoD Session
operationId: edge_cloud_management_api.controllers.network_functions_controller.create_qod_session
requestBody:
description: QoD Session body.
content:
application/json:
schema:
$ref: '#/components/schemas/QoDSchema'
responses:
"200":
description: Session created.
/sessions/{sessionId}:
get:
tags:
- Quality on Demand Functions
summary: Retrieve details of a QoD Session
operationId: edge_cloud_management_api.controllers.network_functions_controller.get_qod_session
parameters:
- name: sessionId
in: path
description: Represents a QoD Session.
required: true
style: simple
explode: false
schema:
type: string
responses:
"200":
description: QoD Session found
"405":
description: Method not allowed
"404":
description: Session not found
delete:
tags:
- Quality on Demand Functions
summary: Remove QoD Session
operationId: edge_cloud_management_api.controllers.network_functions_controller.delete_qod_session
parameters:
- name: sessionId
in: path
description: Represents a QoD Session.
required: true
style: simple
explode: false
schema:
type: string
responses:
"201":
description: QoD Session deleted
"405":
description: Method not allowed
"404":
description: Session not found
# /traffic-influences:
# post:
# tags:
# - Traffic Influence Functions
# summary: Creates a new TrafficInfluence resource
# operationId: edge_cloud_management_api.controllers.network_functions_controller.create_traffic_influence_resource
# requestBody:
# description: TrafficInfluence body.
# content:
# application/json:
# schema:
# $ref: '#/components/schemas/TrafficInfluenceSchema'
# responses:
# "200":
# description: Resource created.
# get:
# tags:
# - Traffic Influence Functions
# summary: Retrieves all TrafficInfluence resources
# operationId: edge_cloud_management_api.controllers.network_functions_controller.get_all_traffic_influence_resources
# responses:
# "200":
# description: Resources retrieved.
# /traffic-influences/{id}:
# get:
# tags:
# - Traffic Influence Functions
# summary: Retrieve details of a TrafficInfluence resource
# operationId: edge_cloud_management_api.controllers.network_functions_controller.get_traffic_influence_resource
# parameters:
# - name: id
# in: path
# description: Represents a TrafficInfluence resource.
# required: true
# style: simple
# explode: false
# schema:
# type: string
# responses:
# "200":
# description: TrafficInfluence resource found
# "405":
# description: Method not allowed
# "404":
# description: Session not found
# delete:
# tags:
# - Traffic Influence Functions
# summary: Remove TrafficInfluence resource
# operationId: edge_cloud_management_api.controllers.network_functions_controller.delete_traffic_influence_resource
# parameters:
# - name: id
# in: path
# description: Represents a TrafficInfluence resource
# required: true
# style: simple
# explode: false
# schema:
# type: string
# responses:
# "201":
# description: TrafficInfluence resource deleted
# "405":
# description: Method not allowed
# "404":
# description: Session not found
/location/retrieve:
post:
tags:
- Location Retrieval Functions
summary: Retrieve the location of a device
description: |
Retrieve the location of a device using the CAMARA Device Location API.
The request is forwarded to the Service Resource Manager which delegates
to the configured network adapter.
operationId: edge_cloud_management_api.controllers.network_functions_controller.retrieve_location
requestBody:
description: Location retrieval request following CAMARA Device Location API.
content:
application/json:
schema:
$ref: '#/components/schemas/RetrievalLocationRequest'
examples:
PhoneNumberExample:
summary: Retrieve location by phone number
value:
device:
phoneNumber: "+123456789"
maxAge: 60
Ipv4Example:
summary: Retrieve location by IPv4 address
value:
device:
ipv4Address:
publicAddress: "198.51.100.1"
publicPort: 59765
maxAge: 120
maxSurface: 10000
responses:
"200":
description: Device location retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/LocationResponse'
"400":
$ref: "#/components/responses/400"
"401":
$ref: "#/components/responses/401"
"404":
$ref: "#/components/responses/404"
"500":
$ref: "#/components/responses/500"
"503":
$ref: "#/components/responses/503"
/partner:
post:
tags:
- FederationManagement
summary: Creates one direction federation with partner operator platform.
# security:
# - oAuth2ClientCredentials:
# - fed-mgmt
# --- truncated at 32 KB (101 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/etsi/refs/heads/main/openapi/camara/operator-platform-edge-cloud-management.yaml