API docs by Redocly

Edge Cloud Client API (2.0)

Download OpenAPI specification:Download

Introduction

Edge Cloud provides a set of SDKs and Libraries containing a collection of operations and resources that assist in creating applications for the many services offered by EdgeXR. Once an application is built and registered, our services locate the nearest cloudlet server, connecting you to one of our edge server instances. Our services will also verify a device's location, ensuring the optimum compute instance is used, and much more, once you are on the edge. Edge Cloud MatchingEngine SDKs and Libraries are available in different languages and platforms, which include Android, Unity, and iOS, allowing for easy application development. The Performance Metrics API, provided with each SDKs, tracks the average latency characteristics of the edge network. To take advantage of this API, you must add your application server’s Application Instance to a list of sites in order to periodically ping them. Within the left navigational menu, scroll to the desired SDK, based on your preferred language or platform, to view the accompanying APIs. To reference these APIs, including their resources and schema, click Edge REST APIs.

MatchEngineApi

FindCloudlet

Find the best application service running on a cloudlet in the Edge Cloud for the client to use, based on proximity and other policies.

Request Body schema: application/json
ver
integer <int64> (API version)

(hidden) Reserved for future use

session_cookie
string (Session Cookie)

Session Cookie from RegisterClientRequest

carrier_name
string (Carrier Name)

(optional) By default, all SDKs will automatically fill in this parameter with the MCC+MNC of your current provider. Only override this parameter if you need to filter for a specific carrier on the DME. The DME will filter for App instances that are associated with the specified carrier. If you wish to search for any App Instance on the DME regardless of carrier name, you can input “” to consider all carriers as “Any”.

object (GPS Location)
object (Tags)

(optional) Vendor specific data

Responses

Request samples

Content type
application/json
{
  • "ver": 0,
  • "session_cookie": "string",
  • "carrier_name": "string",
  • "gps_location": {
    },
  • "tags": {
    }
}

Response samples

Content type
application/json
{
  • "ver": 0,
  • "status": "FIND_UNKNOWN",
  • "fqdn": "string",
  • "ports": [
    ],
  • "cloudlet_location": {
    },
  • "edge_events_cookie": "string",
  • "qos_result": "QOS_NOT_ATTEMPTED",
  • "qos_error_msg": "string",
  • "tags": {
    }
}

GetAppOfficialFqdn

Get an App's official FQDN if configured, which points to a default public cloud instance of the application service that can be used if no Edge Cloud application instances are available.

Request Body schema: application/json
ver
integer <int64> (API version)

(hidden) Reserved for future use

session_cookie
string (Session Cookie from RegisterClientRequest)
object (GPS Location)
object (_(optional)_ Vendor specific data)

Responses

Request samples

Content type
application/json
{
  • "ver": 0,
  • "session_cookie": "string",
  • "gps_location": {
    },
  • "tags": {
    }
}

Response samples

Content type
application/json
{
  • "ver": 0,
  • "app_official_fqdn": "string",
  • "client_token": "string",
  • "status": "AOF_UNDEFINED",
  • "ports": [
    ],
  • "tags": {
    }
}

StreamEdgeEvent

Streams events bidirectionally between device client and the Edge Cloud platform for notifications.

Request Body schema: application/json

(streaming inputs)

session_cookie
string (Session Cookie from RegisterClientReply)
edge_events_cookie
string (Session Cookie from FindCloudletReply)
event_type
string (ClientEdgeEventClientEventType)
Default: "EVENT_UNKNOWN"
Enum: "EVENT_UNKNOWN" "EVENT_INIT_CONNECTION" "EVENT_TERMINATE_CONNECTION" "EVENT_LATENCY_SAMPLES" "EVENT_LOCATION_UPDATE" "EVENT_CUSTOM_EVENT"
object (GPS Location)
Array of objects (Latency Samples if event_type is EVENT_LATENCY_SAMPLES or EVENT_CUSTOM_EVENT)
object (DeviceInfoStatic)
object (DeviceInfoDynamic)
custom_event
string (Custom event specified by the application)
object (_(optional)_ Vendor specific data)

Responses

Request samples

Content type
application/json
{
  • "session_cookie": "string",
  • "edge_events_cookie": "string",
  • "event_type": "EVENT_UNKNOWN",
  • "gps_location": {
    },
  • "samples": [
    ],
  • "device_info_static": {
    },
  • "device_info_dynamic": {
    },
  • "custom_event": "string",
  • "tags": {
    }
}

Response samples

Content type
application/json
{
  • "result": {
    },
  • "error": {
    }
}

QualityOfService

QosPrioritySessionCreate

Creates a QOS priority session (latency or throughput priority) from the client to the app inst by making a call to the operator's priority session API server.

Request Body schema: application/json
ver
integer <int64> (API version)

(hidden) Reserved for future use

session_cookie
string (Session Cookie from RegisterClientRequest)
session_duration
integer <int64> (_(optional)_ QOS Priority Session duration in seconds)
ip_user_equipment
string (IP address of mobile device)
ip_application_server
string (IP address of the application server)
port_user_equipment
string

(optional) A list of single ports or port ranges on the user equipment.

port_application_server
string (_(optional)_ A list of single ports or port ranges on the application server)
protocol_in
string (distributed_match_engineQosSessionProtocol)
Default: "TCP"
Enum: "TCP" "UDP" "ANY"
protocol_out
string (distributed_match_engineQosSessionProtocol)
Default: "TCP"
Enum: "TCP" "UDP" "ANY"
profile
string (- QOS_NO_PRIORITY: Specifies that no priority session should be created - QOS_LOW_LATENCY: Corresponds to a specific set of network parameters for low latency that will be negotiated with the network provider in advance - QOS_THROUGHPUT_DOWN_S: Downlink traffic from AppInst to client is prioritized up to 20Mbps - QOS_THROUGHPUT_DOWN_M: Downlink traffic from AppInst to client is prioritized up to 50Mbps - QOS_THROUGHPUT_DOWN_L: Downlink traffic from AppInst to client is prioritized up to 100Mbps)
Default: "QOS_NO_PRIORITY"
Enum: "QOS_NO_PRIORITY" "QOS_LOW_LATENCY" "QOS_THROUGHPUT_DOWN_S" "QOS_THROUGHPUT_DOWN_M" "QOS_THROUGHPUT_DOWN_L"
notification_uri
string

(optional) URI of the callback receiver. Allows asynchronous delivery of session related events.

notification_auth_token
string (_(optional)_ Authentification token for callback API)
object (_(optional)_ Vendor specific data)

Responses

Request samples

Content type
application/json
{
  • "ver": 0,
  • "session_cookie": "string",
  • "session_duration": 0,
  • "ip_user_equipment": "string",
  • "ip_application_server": "string",
  • "port_user_equipment": "string",
  • "port_application_server": "string",
  • "protocol_in": "TCP",
  • "protocol_out": "TCP",
  • "profile": "QOS_NO_PRIORITY",
  • "notification_uri": "string",
  • "notification_auth_token": "string",
  • "tags": {
    }
}

Response samples

Content type
application/json
{
  • "ver": 0,
  • "session_duration": 0,
  • "profile": "QOS_NO_PRIORITY",
  • "session_id": "string",
  • "started_at": 0,
  • "expires_at": 0,
  • "http_status": 0,
  • "tags": {
    }
}

QosPrioritySessionDelete

Deletes a previously created QOS priority session by making a call to the operator's priority session API server.

Request Body schema: application/json
ver
integer <int64> (API version)

(hidden) Reserved for future use

session_cookie
string (Session Cookie from RegisterClientRequest)
profile
string (- QOS_NO_PRIORITY: Specifies that no priority session should be created - QOS_LOW_LATENCY: Corresponds to a specific set of network parameters for low latency that will be negotiated with the network provider in advance - QOS_THROUGHPUT_DOWN_S: Downlink traffic from AppInst to client is prioritized up to 20Mbps - QOS_THROUGHPUT_DOWN_M: Downlink traffic from AppInst to client is prioritized up to 50Mbps - QOS_THROUGHPUT_DOWN_L: Downlink traffic from AppInst to client is prioritized up to 100Mbps)
Default: "QOS_NO_PRIORITY"
Enum: "QOS_NO_PRIORITY" "QOS_LOW_LATENCY" "QOS_THROUGHPUT_DOWN_S" "QOS_THROUGHPUT_DOWN_M" "QOS_THROUGHPUT_DOWN_L"
session_id
string (QOS Priority Session ID to be deleted)
object (_(optional)_ Vendor specific data)

Responses

Request samples

Content type
application/json
{
  • "ver": 0,
  • "session_cookie": "string",
  • "profile": "QOS_NO_PRIORITY",
  • "session_id": "string",
  • "tags": {
    }
}

Response samples

Content type
application/json
{
  • "ver": 0,
  • "status": "QDEL_UNKNOWN",
  • "tags": {
    }
}

Session

RegisterClient

Registers the client with the closest Distributed Matching Engine (the nearest edge location in the Operator network) and validates the legitimacy of the mobile subscriber. All session information is encrypted.

Request Body schema: application/json
ver
integer <int64> (API version)

(hidden) Reserved for future use

org_name
string (App Organization Name)

App developer organization name.

app_name
string (App Name)

Name of your application.

app_vers
string (App Version)

Application version.

carrier_name
string (Carrier Name)

(hidden) Reserved for future use

auth_token
string (Authentication Token)

(optional) An authentication token supplied by the application.

unique_id_type
string (Unique ID Type)

(optional) Type of unique ID provided by the client. If left blank, a new Unique ID type will be assigned in the RegisterClient Reply.

unique_id
string (Unique ID)

(optional) Unique identification of the client device or user. May be overridden by the server. If left blank, a new Unique ID will be assigned in the RegisterClient Reply.

object (Tags)

(optional) Vendor specific data

Responses

Request samples

Content type
application/json
{
  • "ver": 0,
  • "org_name": "string",
  • "app_name": "string",
  • "app_vers": "string",
  • "carrier_name": "string",
  • "auth_token": "string",
  • "unique_id_type": "string",
  • "unique_id": "string",
  • "tags": {
    }
}

Response samples

Content type
application/json
{
  • "ver": 0,
  • "status": "RS_UNDEFINED",
  • "session_cookie": "string",
  • "token_server_uri": "string",
  • "unique_id_type": "string",
  • "unique_id": "string",
  • "tags": {
    }
}

Location

VerifyLocation

Verifies that the GPS coordinates accurately report the actual location of the device.

Request Body schema: application/json
ver
integer <int64> (API version)

(hidden) Reserved for future use

session_cookie
string (Session Cookie)

Session Cookie from RegisterClientRequest

carrier_name
string (Carrier Name)

Unique carrier identification (typically MCC + MNC)

object (GPS Location)
verify_loc_token
string (Verify Location Token)

Must be retrieved from TokenServerURI

object (Tags)

(optional) Vendor specific data

Responses

Request samples

Content type
application/json
{
  • "ver": 0,
  • "session_cookie": "string",
  • "carrier_name": "string",
  • "gps_location": {
    },
  • "verify_loc_token": "string",
  • "tags": {
    }
}

Response samples

Content type
application/json
{
  • "ver": 0,
  • "tower_status": "TOWER_UNKNOWN",
  • "gps_location_status": "LOC_UNKNOWN",
  • "gps_location_accuracy_km": 0,
  • "tags": {
    }
}