Integrate with SPEKTRA Edge
This section is for developers calling SPEKTRA Edge from their own applications, scripts, and automation. If you are setting up devices or deploying applications from the dashboard, start with Learn instead. If you want to build your own service that runs on the platform, see Build a service.
Everything the platform does, it does through its API. The dashboard reads and
writes the same API you will; so does the cuttle CLI. Nothing you see in the
dashboard is off-limits to automation, and nothing you automate is second-class.
In this section
Read in order the first time — each page assumes the one before it.
Get started — authenticate and make your first call, in about ten minutes.
Authentication — service accounts, API keys, and how to hold credentials safely in CI and in long-running services.
Resource names — how resources are addressed, why most of them carry a region, and how to build a name you have never seen before.
Reading resources — the filter language, field masks and views, ordering, and pagination. The largest page here, and the one that pays for itself fastest.
Watching for changes — subscribe to a live stream of changes instead of polling.
Errors and limits — what the platform returns when something is wrong, which failures are worth retrying, and the two update-time mistakes that silently destroy data.
Deployment status — drive a rollout from your own code, and read back whether it actually worked.
Choosing a protocol
The same API is exposed three ways. Pick once, at the start.
| Protocol | Use it when | Caveats |
|---|---|---|
| gRPC | You are writing a service, a daemon, or anything long-lived. This is the native protocol. | Needs a gRPC library and the .proto files or an SDK. |
| gRPC-Web | You are calling from browser JavaScript. | Served through a proxy; a browser cannot speak plain gRPC. |
| REST/JSON | You are writing a shell script or a small one-off tool. | Generated automatically from the gRPC definitions. See the warning below. |
gRPC runs over HTTP/2, so its traffic passes through HTTP proxies and HTTP/2-compliant firewalls like any other HTTPS traffic. Choosing the native protocol does not usually mean asking your network team for an exception.
Streaming calls — including watch — are natural over gRPC and awkward or unavailable over REST. If you need a live view of anything, choose gRPC.
The REST interface is derived mechanically from the gRPC service definitions and is provided as a convenience. It is not supported, and its specification is subject to change without notice. Use it for scripting and exploration; build a product on gRPC.
SDKs
Each SDK ships the .proto definitions so you can generate a client for any
language, plus a ready-made client library for Go. For how to use the
libraries, read the README in the repository — that is where installation and
usage for each SDK is documented. Per-service API reference lives in
docs/apis inside each repository, and on this site under Service APIs.
| SDK | Contents |
|---|---|
| edgelq-sdk | The main SDK: IAM, devices, applications, monitoring, logging, and the rest of the core services. |
| watchdog-sdk | Service Experience Insights resources such as Probe and ProbingTarget. SEI also uses IAM and monitoring from the main SDK. |
| goten-sdk | The Goten framework types the other two SDKs are built on. You will rarely import it directly. |
Related
- cuttle CLI — the fastest way to explore the API by hand and to check what a request returns before you write code against it.