Coldwave Documentation

Appearance

Accessing the API ​

This page explains the technical basics of calling the coldwave backend API.

It is meant as a low-level reference for all kinds of clients (backends, CLI tools, scripts). For building full web or mobile applications, see the Application Developer Guide section, especially:

1. Base URL and versioning ​

All REST endpoints are exposed under a versioned base path:

text
https://<<URL>>/api/v1/...
  • <<URL>> is the deployment-specific host name of your backend.
  • v1 is the current REST API version.
  • All module endpoints (IAM, Metadata, Service, Schema, Streams, Timestream, Alarms, Notes, …) live under this base path and are documented in their respective module pages.

2. Authentication overview ​

The coldwave backend can be deployed with or without IAM:

  • Without IAM

    • All endpoints are accessible without a token.
    • This is only recommended for internal/testing deployments.

  • With IAM enabled (recommended)

    • Every request (except a few public endpoints like sign-up) must include a valid token.
    • Tokens are short-lived JWTs issued by the IAM module.
    • API keys can be used for non-interactive clients.

The full flows for user login, tokens, refresh tokens and API keys are explained in the IAM & Authentication guide. This page only shows how to attach tokens to HTTP requests.

2.1 User access tokens ​

Once you have obtained an access token from IAM, send it as a Bearer token in the Authorization header:

bash
curl --location 'https://<<URL>>/api/v1/devices?depth=1'   --header 'Authorization: Bearer <<TOKEN>>'

Replace <<TOKEN>> with the token returned by the IAM /api/v1/iam/token endpoint.

2.2 API keys ​

For non-interactive clients (backend services, batch jobs, CLI tools), the IAM module can issue API keys. API keys:

  • belong to a specific IAM group + role,
  • inherit their permissions and device/service scope,
  • are sent as a dedicated header (defined per deployment) instead of a Bearer token.

The lifecycle and exact header format are described in the IAM module documentation.

3. Request and response conventions ​

3.1 HTTP methods and JSON ​

  • All endpoints use standard HTTP methods (GET, POST, PUT, PATCH, DELETE).
  • Request and response bodies (where present) are JSON unless otherwise noted.
  • For write operations, always send Content-Type: application/json.

Example:

bash
curl --location 'https://<<URL>>/api/v1/meta'   --header 'Authorization: Bearer <<TOKEN>>'   --header 'Content-Type: application/json'   --data '{
    "deviceIdentifier": "CFF349041010ADC",
    "meta": {
      "name": "Lift A – Entrance East",
      "location": "Building A / Entrance"
    }
  }'

3.2 Status codes ​

The backend uses conventional HTTP status codes:

  • 200 OK – successful request with a JSON body.
  • 201 Created – resource created.
  • 204 No Content – successful request without body (common for PUT/DELETE operations).
  • 400 Bad Request – malformed payload or invalid parameters.
  • 401 Unauthorized – missing or invalid token.
  • 403 Forbidden – token is valid but does not have the required permissions.
  • 404 Not Found – resource does not exist or is not visible to this token.
  • 5xx – server-side errors (transient or misconfiguration).

If present, error bodies are JSON and describe the problem in more detail.

3.3 Access section per endpoint ​

Each module page lists, for every endpoint:

  • required resource (e.g. meta, service, alarms.rules, notes),
  • allowed actions (e.g. create, read, update, delete).

Your token must carry matching permissions to call that endpoint successfully.

4. Typical data access pattern ​

Most coldwave applications work with three core modules:

  • Service – current values and commands for device services
  • Schema – human-readable property names, units, enums and UI hints
  • Metadata – device names, locations, deployment info

A minimal pattern to fetch the current state is:

  1. Schemas (once at startup, or on schema changes):

    bash
    curl --location 'https://<<URL>>/api/v1/schemas?depth=1'      --header 'Authorization: Bearer <<TOKEN>>'

  2. Services or devices (current values):

    bash
    curl --location 'https://<<URL>>/api/v1/services?depth=2&raw=true'      --header 'Authorization: Bearer <<TOKEN>>'
# or
curl --location 'https://<<URL>>/api/v1/devices?depth=2&raw=true'      --header 'Authorization: Bearer <<TOKEN>>'

  3. Metadata (device-related information):

    bash
    curl --location 'https://<<URL>>/api/v1/meta?depth=1'      --header 'Authorization: Bearer <<TOKEN>>'

How to turn these responses into a frontend state model, and how to map properties via schema, is described in detail in the Application Developer Guide.

5. Websocket access (overview) ​

For realtime updates (property changes, alarms, notes, livestreams, IAM events), use the Websocket endpoint.

In browsers and SPAs, the recommended flow is:

  1. Request a ticket with your Bearer token:

    bash
    curl --location 'https://<<URL>>/api/v1/events/ticket'      --header 'Authorization: Bearer <<TOKEN>>'

  2. Open a websocket using the ticket:

    ts
    const ws = new WebSocket('wss://<<URL>>/api/v1/events/' + ticket);

  3. Handle incoming JSON messages (all contain a type field).

The full connection lifecycle, event routing and recommended patterns are covered in the Websocket & Events guide.

For backend/CLI clients that can send headers in the upgrade request, a direct GET /api/v1/events with Authorization: Bearer <<TOKEN>> is also available.

6. CORS, SPA and browser integration ​

If you serve a single-page application (SPA) from a different origin than the backend, you may need to adjust:

  • CORS settings (allowed origins, headers, methods)
  • Single Page Application settings (asset serving, routing)

These aspects are configured via the Single Page Application and CORS modules and documented in their respective module pages. They are deployment concerns and usually do not affect backend-to-backend integrations.

7. Where to go next ​

  • For application-level architecture, state handling and UI patterns, start with the Application Developer Guide.
  • For module-specific details, see the individual module pages (IAM, Metadata, Schema, Service, DeviceInfo, Streams, Timestream, Alarms, Notes, …).
  • For language-specific examples (Node.js and others), see the Example Code page and the GitHub example repositories.