This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

SPEKTRA Edge Integration Guide

How to integrate SPEKTRA Edge services to your system.

All of SPEKTRA Edge’s functionality is provided by the API. The web dashboard that users normally access retrieves and displays all data via the API. The cuttle command also uses the same API to retrieve data. In other words, all data displayed on the dashboard and values returned by the cuttle command can be retrieved via the API.

Supported API types

The SPEKTRA Edge controller is provided with three API protocols.

gRPC

The SPEKTRA Edge controller’s main API is provided as a gRPC endpoint. Starting with the cuttle command, clients using the SPEKTRA Edge controller communicate with the SPEKTRA Edge controller using gRPC. gRPC is implemented over HTTP2, so gRPC traffic can pass through any HTTP proxy or HTTP2-compliant firewalls.

gRPC is the native protocol for SPEKTRA Edge, and it is recommended that gRPC be used if there are no implementation constraints.

gRPC-web

The SPEKTRA Edge controller also supports the gRPC-web protocol. gRPC-web is a protocol for using gRPC in a web browser. It is implemented over HTTP2, but due to various limitations cannot be used directly in a browser’s JavaScript environment. In contrast, gRPC-web works as-is in current browsers. The SPEKTRA Edge controller supports the gRPC-web protocol by using the Envoy proxy.

gRPC-web is recommended for calling the SPEKTRA Edge Controller API from a web browser.

REST

The SPEKTRA Edge controller also supports API calls via regular HTTP requests. It is possible to perform CRUD operations on each resource using the so-called REST method.

The REST API is automatically generated from gRPC API definitions and is provided by the Envoy proxy. API calls via REST are useful, for example, for simple scripting. Please note, however, that the REST API is automatically generated and is not supported in any way. Specifications are subject to change without notice.

SDK

To enable third-party client development using gRPC, an SDK is provided; the SDK is divided into several parts, each published as a different Github repository.

Each SDK includes a gRPC definition file (.proto) that allows users to generate their own code, as well as a client library for the Go language. Please refer to the README file in the repository for details on how to use the libraries.

API references (list of available APIs, parameters, etc.) are included in the docs/apis of each SDK.

SPEKTRA Edge SDK

https://github.com/cloudwan/edgelq-sdk

SPEKTRA Edge SDK is the main SDK and contains general-purpose functionality such as IAM, Devices, and Applications.

Watchdog SDK

https://github.com/cloudwan/watchdog-sdk

The Watchdog SDK is an SDK that contains the resources used in Service Experience Insights. Agents (Probe) and other resources are included in this SDK. Please note that Service Experience Insights as a whole also uses the IAM and Monitoring services included in the SPEKTRA Edge SDK.

Goten SDK

https://github.com/cloudwan/goten-sdk

Goten SDK is the SDK that contains the Goten framework referenced by SPEKTRA Edge SDK and Watchdog SDK, and is used indirectly when using SPEKTRA Edge SDK and Watchdog SDK.

1 - Quick Start

Quickly start the API integration with SPEKTRA edge platform.

The easiest way to perform API integration is to script using the REST API (although it should be noted that the REST API is not officially supported).

Authentication during integration

Service accounts are commonly used for authentication in automated environments. See the “Service Accounts and Service Account Keys” section for more information on service accounts.

The following creates a service account for automation, generates an API key for the REST API, and assigns the services/iam.edgelq.com/roles/scope-admin role.

## Create service account "automation".
cuttle iam create service-account --project $PROJECT automation

## Generate API key for the above service account
cuttle iam create service-account-key \
  --parent projects/$PROJECT/regions/eu1/serviceAccounts/automation \
  --algorithm API_KEY api_key

## Assign the scope-admin role to the above service account
cuttle iam create role-binding \
  --project $PROJECT \
  --member "serviceAccount:automation@$PROJECT.eu1.serviceaccounts.iam.edgelq.com" \
  --role "services/iam.edgelq.com/roles/scope-admin"

Authentication with the REST API is done using Authorization in the HTTP header. Set the API key generated above as the Bearer token.

Sample Scripts

The following are sample scripts that implement each of the simplest requests on Node JS.

const fetch = require('node-fetch');

const apiKey = "<API_KEY>";
const projectName = "<PROJECT_NAME>";

const regionName = "eu1"
const baseDomain = "apis.edgelq.com"

// callAPI sends a request to the REST endpoint with the API key.
const callAPI = async (method, url, body) => {
  const parsed = new URL(url);
  // Set the API key to the Authorization header.
  const authHeaders = {"Authorization": `Bearer ${apiKey}`}
  return await fetch(url, {method: method, body: body, headers: authHeaders}); }
};

(async () => {
  // To get a resource, simply issue a GET request to a fully qualified resource name.
  // Ex. Get the Project
  const iamGetProject = await callAPI("GET", `https://iam.${baseDomain}/v1alpha2/projects/${projectName}`, null);
  console.log(`Get Project: ${await iamGetProject.text()}\n`);

  // To list resources, issue a GET request to the resource name
  // Ex. List Probes (a.k.a. Probes) under the project
  const watchdogListProbes = await callAPI("GET", `https://watchdog.${baseDomain}/v1alpha2/projects/${projectName}/regions/${regionName}/ probes`, null);
  console.log(`List Probes: ${await watchdogListProbes.text()}\n`);

  // To add filters to the list request, append `filter=<expression>` to the parameter (with escaping)
  // Ex. List Probes whose spec.enabled field is enalbed
  const watchdogListProbesWithFilter = await callAPI("GET", `https://watchdog.${baseDomain}/v1alpha2/projects/${projectName}/regions/${regionName}/${? regionName}/probes?filter=${encodeURIComponent(`spec.enabled=true`)}`, null);
  console.log(`List Probes With Filter: ${await watchdogListProbesWithFilter.text()}\n`);

  // To create a resource, issue a POST request.
  // Ex. Create a new ProbingTarget
  const watchdogCreateTargetNTT = await callAPI("POST", `https://watchdog.${baseDomain}/v1alpha2/projects/${projectName}/probingTargets`, JSON.stringify({
    "name": `projects/${projectName}/probingTargets/ntt`,.
    "display_name": "NTT", "address": "", "name": "", "address".
    "address": "www.global.ntt", // "mode": 1, // IC
    "mode": 1, // ICMP
  }));
  console.log(`Create ProbingTarget: ${await watchdogCreateTargetNTT.text()}\n`);

  // To update a resource, issue a PUT request to a fully qualified resource name.
  // To avoid unexpected overwriting with empty values, use update-mask to specify fields to be updated by the request.
  // Ex. Update the addresses of the ProbingTarget
  const watchdogUpdateTargetNTT = await callAPI("PUT", `https://watchdog.${baseDomain}/v1alpha2/projects/${projectName}/probingTargets/ ntt?updateMask=${encodeURIComponent(`address`)}`, JSON.stringify({
    "address": "group.ntt",.
  })));
  console.log(`Update ProbingTarget: ${await watchdogUpdateTargetNTT.text()}\n`);


  // To delete a resource, issue a DELETE request to a fully qualified resource name.
  // To avoid unexpected overwriting with empty values, use update-mask to specify fields to be updated by the request.
  // Ex. Update the addresses of the ProbingTarget
  const watchdogDeleteTargetNTT = await callAPI("DELETE", `https://watchdog.${baseDomain}/v1alpha2/projects/${projectName}/probingTargets /ntt`, null);
  console.log(`Delete ProbingTarget: ${await watchdogDeleteTargetNTT.text()}\n`);
})();

To obtain SEI metrics information from the Monitoring service, please refer to the following code (Body portion only).

(async () => {
  // for resource.type, run `cuttle monitoring list monitored-resource-descriptors`
  // for metric.type, run `cuttle monitoring list metric-descriptors`
  
  // https://github.com/cloudwan/edgelq-sdk/blob/febf9a9011ef643cad7fffa583cff78eadeb0c98/monitoring/proto/v4/common.proto
  const query=`https://monitoring.${baseDomain}/v4/projects/${projectName}/timeSeries?filter=${encodeURIComponent(`resource.type=" watchdog.edgelq.com/probe" AND metric.type="watchdog.edgelq.com/probe/session/latency"`)}&aggregation.alignmentPeriod=60s& aggregation.crossSeriesReducer=REDUCE_NONE&aggregation.perSeriesAligner=ALIGN_MEAN&interval.startTime=${encodeURIComponent("2023- 05-24T00:00:00Z")}&interval.endTime=${encodeURIComponent("2023-05-25T00:00:00Z")}`

  const monitoringListTimeSeries = await callAPI("GET", query, null);
  console.log(`Query Result: ${await monitoringListTimeSeries.text()}\n`);
})();