Dedicated Networks APIs High Level Description

Purpose of Document

This document is intended as a subproject internal artifact to get started with better explanations and descriptions of the Dedicated Networks APIs.

However, it is written in the style of external documentation, so that the content can be re-used where needed, for example when writing documentation in the API specification, or to have additional documentation for developer friendliness.

The idea is to identify the high-level descriptions and suitable figures. It is not expected that individual parameter names would be described here (at least initially).

There is intentional duplication in the content since we have 3 yaml files. At the moment trying to keep each section relatively independent and complete.

Introduction to Dedicated Networks

The CAMARA Dedicated Networks APIs enable programmatic creation, management, and use of dedicated network connectivity resources on a public network, without the need for in-depth knowledge of telecommunications systems.

Dedicated Networks can be managed based on varying geographic coverage and deployment durations. Once created and active, they can be utilized by one or more devices with different quality and performance characteristics (within the limits of the network profile).

Dedicated Networks are beneficial in a variety of cases, and are particularly well-suited when assured network performance is needed, such as during large events, for critical business applications, or scenarios demanding a consistent experience.

CAMARA Dedicated Networks APIs consists of 3 API specifications:

· Dedicated Networks Profiles (dedicated-network-profiles.yml)

· Dedicated Networks (dedicated-network.yml)

· Dedicated Networks Accesses (dedicated-network-accesses.yml)

A high-level sequence of steps involved when using Dedicated Networks API is depicted in the diagram below:

Figure 1 High-level sequence of steps

Pre-requisites

Before Dedicated Networks APIs can be invoked, relevant agreements need to be in place between the API Invoker and the API Provider. This typically involves setting up API Invoker accounts on the API Provider platform, and obtaining relevant URLs and access credentials.

The API Invoker and API Provider also need to agree on the required capabilities and performance targets (network profiles), and the geographic areas (service areas) where dedicated connectivity resources are needed.

An API Provider may provide a catalog where API Invokers can discover the various options available. API Invokers choose from available network profiles and service areas offered by the API Provider. The API Provider then provisions and enables these selected capabilities, making them available for the API Invoker’s use.

This discovery, selection and preparation (essentially a negotiation or pre-ordering phase) is outside the scope of the Dedicated Networks APIs.

At completion of the pre-requisites, no Dedicated Networks (instances) are created. An API Invoker can list and view details of network profiles that are applicable to their account permissions and service agreements using the Dedicated Networks Profiles API.

Figure 2 Pre-requisites for Dedicated Networks APIs

Dedicated Networks Profiles API

Dedicated Networks Profiles describe the capabilities and performance targets of the dedicated network connectivity resources. Each network profile is uniquely identified by a profileId and contains information about the maximum number of devices allowed, the aggregated bandwidth to be reserved, and a set of allowed QoS profiles that devices can later use.

An API Invoker can view the list of network profiles that are applicable to their account permissions and service agreements using the Dedicated Networks Profiles API.

An API Invoker needs to use a valid profileId when creating Dedicated Networks which are identified using this API.

This API does not return information about the service areas or service time since these are unique for every Dedicated Network (instance).

Dedicated Networks API

The Dedicated Networks API enable programmatic creation and lifecycle management of dedicated network connectivity resources on a public network.

Dedicated Networks can be managed based on varying geographic coverage and deployment durations.

dedicated-network.yml provides a /networks endpoint that allows API Invokers to create, delete Dedicated Networks, and list and view details.

Creating Dedicated Networks

Dedicated Networks are created by performing a POST method on the /networks endpoint.

The API Invoker needs to provide the following input parameters to create a dedicate network:

the chosen network profile (profileId)
the service area (serviceArea)
the service start and end times (serviceTime).
optionally, callback related information through sink and sinkCredential parameters to receive notifications about the lifecycle events of the Dedicated Networks.

The API returns a networkId which is used later to allow or revoke accesses from devices.

The simplified lifecycle states in Dedicated Networks are depicted below:

Figure 3 Simplified Dedicated Networks Lifecycle states

Todo: Add some text about the states, e.g., that request may be rejected during validation, FAILED states and potentially TERMINATED states are not depicted. May be not all DNs need to go through all states each time, may be something can go straight to active?

The diagram below further depicts lifecycle state changes based on who or what tiggers them.

Figure 4 Roles and triggers for Dedicated Networks lifecycle state changes

Querying Dedicated Networks

The list of available Dedicated Networks can be viewed performing a GET method on the /networks endpoint.

The API returns the list of dedicated networks (the list can be empty).

Deleting Dedicated Networks

A Dedicated Network already instantiated (with a Network identifier as NetworkID) can be destroyed performing a DELETE method on the /networks/{networkID} endpoint.

The API simply return the http code to confirm the successful deletion.

Dedicated Network Accesses API

Once a Dedicated Network is in an ACTIVE state, devices must be allowed to use the reserved connectivity resources.

A device is allowed access by performing aPOST operation on the /accesses.

The API Invoker provides the following information

· the networkId to which a device is being granted access

· the device object to identify the device

· Optionally, a default QoS profile can be set for the devices

· Optionally, a subset of QoS profiles from this Dedicated Network instance can be provided to further restrict which QoS profiles a specific device can access

The API returns an accessId which is needed to query the status of the access (GET /accesses/{accessId}) and to revoke access (DELETE accesses/{accessId}).

Todo: Device access states, otherwise should say that there can be a delay between the API endpoint returning something and the device access being granted / revoked?

Detailed high-level flow

The diagram below attempts to depict the complete flow including API endpoint, response codes, and key parameters.

Figure 5 High Level Flow with additional details

CAMARA Project