Dedicated Networks APIs High Level Description

Purpose of Document

This document is intended as a subproject internal artefact to get started with explanations and descriptions of the Dedicated Network APIs. It will be replaced (over time) by the description section in the yaml files and in the API Documentation page.

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 description of the workflow, key concepts and suitable figures. It is not expected that individual parameter names would be described here (at least initially).

Introduction to Dedicated Networks

Dedicated Networks enable dedicated use of public network connectivity resources by reserving some of these resources for use by devices and applications. To these devices and applications, the reserved resources appear as their own virtual or logical network. Please check here for several usage scenarios for Dedicated Networks.

Fixed and Mobile Networks already offer the capability of separating devices into different networks. These concepts are sometimes called logical networks or virtual private networks. Multiple of these networks can coexist on the same physical network and can separate target traffic from other traffic for assured performance, enhanced security and other scenarios where consistent experience is required.

There are different options to technically realize a Dedicated Network. For example:

Using 5G Network Slices (see 3GPP 23.501, clause 5.15)
Using 5G Non-Public Networks (NPN), specifically the Public Network Integrated NPN (PNI-NPN), see 3GPP 23.501, clause 5.30)
Using a separate 4G APN (see 3GPP 23.401) or 5G DNNs (see 3GPP 23.501). Note, a DNN is equivalent to an APN, per 3GPP 23.003.

Dedicated Networks abstract the complexity across Network Provider realizations to enable coherent use of diverse network capabilities.

A Dedicated Network is often only needed for a specific time duration (e.g. one hour) and at specific locations (e.g. the area of a festival). These are referred to as Service Time and Service Area.

The CAMARA Dedicated Network APIs allow API Consumers to programmatically manage Dedicated Networks, without the need for in-depth knowledge of telecommunications systems.

API Consumers have control over which devices are allowed to access and use the reserved network connectivity resources. In addition, network connectivity characteristics, for example, routing and performance may be individually tailored for each device.

Detailed characteristics, behaviors and costs pertaining to Dedicated Networks are typically described by the API Provider in the terms and conditions. Such terms and conditions may also contain obligations and restrictions.

An API Provider realizes Dedicated Networks based on the physical network resources managed by a Network Provider. An API Provider can be the Network Provider.

Key roles

Role Name	Description

Role Name	Description
API Consumer	The entity that consumes the Dedicated Network APIs
API Provider	The entity that provides the Dedicated Network APIs
Network Provider	The entity that provides the physical network resources

Dedicated Network APIs

The CAMARA Dedicated Network APIs allow for programmatic management of Dedicated Networks, without the need for in-depth knowledge of telecommunications systems.

The APIs are summarized in the table below followed by a brief description. Detailed descriptions are provided within each specification.

API	Purpose of the API	Key Abstractions and concepts

API	Purpose of the API	Key Abstractions and concepts
Dedicated Network API	Reservation and lifecycle management of network connectivity resources for dedicated use.	A Dedicated Network is a logical resource and is used to embody the reservation of network connectivity resources in the physical network. Initiating a new reservation request using this API results in a new Dedicated Network resource being created. The Dedicated Network undergoes various lifecycle States including REQUESTED, RESERVED, ACTIVATED and TERMINATED. Reservation of resources occurs based on the selected Network Profile, duration when the reservation is needed (Service Time) and geographical areas where the service is needed (Service Area).
Dedicated Network Profiles API	Discovery of predefined set of network capabilities and performance characteristics	A Network Profile represents a predefined set of network capabilities and performance characteristics that can be applied when creating dedicated networks. Each profile represents a validated, supported configuration that has been pre-approved in the terms and conditions between the API Provider and API Consumer.
Dedicated Network Accesses API	Managing access to the Dedicated Network, i.e., controlling which devices may benefit from the reserved resources and capabilities	A Device Access represents the permission for a specific device to use a Dedicated Network's reserved connectivity resources. The usage of resources can be tailored to each device within the constraints of the applicable Network Profile.

A high-level sequence of steps involved when using Dedicated Network APIs is depicted in the diagram below and further described in their respective sections.

Figure: High-level sequence of steps

graph TD
    0[Complete Pre-requisites]
    A[Choose Dedicated Network Profile]
    B[Create a Dedicated Network]
    C[Create Device Accesses]
    D[Allowed devices can use reserved network connectivity resources]

    0 --> A
    A --> B
    B --> C
    C --> D

Pre-requisites

Before Dedicated Network APIs can be invoked, relevant agreements need to be in place between the API Consumer and the API Provider. Conceptually, the agreement contains all the different terms and conditions, which typically include price, service descriptions and conditions. It also includes obligations and restrictions possibly for both, the API Provider and the API Consumer, etc.

An API Provider may provide a catalog where API Consumers can get an overview of the various options available. For example, there may be a catalog of available APIs, and a catalog of available parameter sets for each of the APIs.

The API Provider may also offer a procedure for requesting additional customization, for example, additional Service Areas or Network Profiles. Such a procedure can leverage conventional methods such as emails or phone conversations.

API Consumers selects from available Network Profiles and Service Areas offered by the API Provider which then become part of the agreed terms and conditions.

This preparation phase is outside the scope of the Dedicated Network APIs.

As result of the agreement on the terms and conditions, the following aspects are determined

URLs and credentials for the API Consumer to use
A set of capabilities and performance targets (Network Profiles) that an API Consumer is eligible to use
A set of geographic areas (Service Areas) that an API Consumer is eligible to use
The API Consumer is aware about the terms and conditions (incl price), when selecting different parameter or parameter combinations according to the conditions.

Note that, at completion of the pre-requisites, no network connectivity resources are reserved, i.e., no Dedicated Network is created.

Detailed high-level flow

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

Figure: High Level Flow with additional details

sequenceDiagram
    participant App as API Consumer (Application)
    participant P as Profiles API
    participant N as Networks API
    participant A as Accesses API
    participant Network as Physical Network
    participant D as Device(s)

    Note over App,D: Pre-requisites completed

    rect lightcyan
        note right of App: Selection of Profile needed for Dedicated Network
        App->>P: GET /profiles
        P->>App: 200 OK Profiles [profileId, ...]
    end

    rect lightcyan
        note right of App: Creation of a Dedicated Network
        App->>N: POST /networks (profileId, serviceArea, serviceTime, ...)
        N->>App: 201 ACCEPTED (networkId, status=REQUESTED)


         N <<-->> Network: Provisioning / configuration as needed<br> Managed by API Provider and Network Provider<br>  Outside scope of the Dedicated Network APIs
        alt Callback enabled
            N-->>App: Optional callback: (networkId, status=RESERVED)
            N-->>App: Optional callback: (networkId, status=ACTIVATED)
        else Polling
            App->>N: GET /networks/{networkId}
            N-->>App: 200 OK (networkId, status=ACTIVATED)
        end
    end

    rect lightcyan
        note right of App: Dedicated Network Accesses API
        loop Create Access resource for a given device to the given network
            App->>A: POST /accesses (networkId, device)
            A->>App: 200 OK Access created (accessId)
        end

        A <<-->> Network: Provisioning / configuration as needed<br> Managed by API Provider and Network Provider<br>  Outside scope of the Dedicated Network APIs

        loop Delete a previously created Access resource
            App->>A: DELETE /accesses (accessId)
            A->>App: 200 OK Access deleted
        end
    end


    Note over App,D: While Dedicated Network in ACTIVATED state

    loop One or more devices
        D-->>Network: Connect to network
        Network-->>D: Connection established / denied
    end

Dedicated Network API

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

A Dedicated Network is a logical resource and is used to embody the reservation of network connectivity resources in the physical network. The act of reservation is equivalent to creating a new Dedicated Network resource via the REST APIs.

A Dedicated Network undergoes various States including REQUESTED, RESERVED, ACTIVATED and TERMINATED.

Reservation of resources occurs based on the selected Network Profile, duration when the reservation is needed (Service Time) and geographical areas when the service is needed (Service Area).

The Dedicated Network API provides a /networks endpoint that allows API Consumers to create a Dedicated Network, delete the Delete Network, list the existing Dedicated Networks and view details of a specific Dedicate Network.

Creating a Dedicated Network

A Dedicated Network is created by performing a POST operation on the /networks endpoint.

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

the chosen Network Profile (profileId)
the Service Area
the service start and end times (Service Time).
Optionally, callback related information through sink and sinkCredential parameters to receive notifications about the lifecycle events of the network.

The API returns a networkId. The networkId is a unique identifier of the network, which remains unchanged during its lifetime. The networkId is required when creating Device Accesses.

On successful acceptance of the request, an HTTP resource is created. The response always returns a REQUESTED State. Reserved resources are only usable when the network is in ACTIVATED state.

A normal lifecycle is depicted below:

Figure: Normal lifecycle

stateDiagram-v2
    [*] --> REQUESTED: POST /networks
    REQUESTED --> RESERVED: Dedicated Network use is confirmed
    RESERVED --> ACTIVATED: Dedicated Network ready for use
    ACTIVATED --> TERMINATED: Dedicated Network service time expires

A more detailed explanation of the states is provided below:

Figure: Dedicate Network States

stateDiagram-v2
    [*] --> REQUESTED: POST /networks
    REQUESTED --> RESERVED: Use is confirmed
    RESERVED --> ACTIVATED: Ready for use
    ACTIVATED --> TERMINATED: Service time expires
    REQUESTED --> ACTIVATED: If requested with current Service Time
    RESERVED --> TERMINATED: Failed to reserve resources

A network in REQUESTED state is not (yet) committed by the Network Provider.

A network in RESERVED state is committed to be available for use during the Service Time by the Network Provider.

The targeted resources of the network are free to be used by other users or for other purposes, while the network is in RESERVED state.

Reserved resources are only usable when the network is in ACTIVATED state.

The network may enter the ACTIVATED state directly after the REQUESTED state if the service start time has been reached when the API Provider successfully completed the resource reservation.

The network may enter the TERMINATED state directly after the REQUESTED state if the API Provider could not complete the resource reservation.

A network in TERMINATED state cannot be modified anymore and should be deleted. If not deleted by the API Consumer, the representing HTTP resource (URL) may be removed by the API Provider.

Querying a Dedicated Network

To be expanded

Deleting A Dedicated Network

To be expanded

Dedicated Network Profiles API

A Dedicated Network Profile represents a predefined set of network capabilities and performance characteristics that can be applied when creating a Dedicated Network. It enables API Consumers to understand the capabilities they can expect when using the reserved network connectivity resources. A Network Profile is a validated, supported configuration that has been pre-approved between the API Provider and API Consumer.

A Network Profile contains information about the maximum number of devices allowed, the aggregated throughput to be provided, and a set of allowed QoS Profiles that devices can use when having access to the Dedicated Network. A detailed description of the individual parameters may be included within the terms and conditions.

The key characteristics of the API include:

Network Profiles are read-only resources from the API Consumer perspective
They are discoverable through GET operations
Each Network Profile has a unique identifier (profileId)
The profileId serves as a reference when creating a Dedicated Network
The API returns only Network Profiles that the API Consumer is eligible to use based on their agreements

Dedicated Network Accesses API

A Device Access represents the permission for a specific device to use a Dedicated Network's reserved connectivity resources. Only devices for which a Device Access resource has been created can use the connectivity resources allocated for that network. The usage of resources can be tailored to each device within the constraints of the applicable Network Profile.

A Device Access is created by performing a POST operation on the /accesses endpoint.

The API Consumer provides the following information

the networkId to access is given
the device (CAMARA device object) to identify the device. Either a MSISDN or a Network Access Identifier can be used.
Optionally, a default QoS Profile can be set for the device
Optionally, a subset of QoS Profiles from this network can be provided to further restrict which QoS Profiles the device can access

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

First draft

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