REST and gRPC API

Quick Start

Enable REST in your config:

environment {
    api-server {
        rest {
            enabled true;
            server { ip 127.0.0.1; port 8081; }
        }
    }
}

REST uses plaintext HTTP and only binds loopback addresses. Use authenticated gRPC with TLS for management from a non-loopback address.

Or via environment variable:

ze.api-server.rest.enabled=true
ze.api-server.rest.listen=127.0.0.1:8081

Query the API:

curl http://localhost:8081/api/v1/commands
curl -X POST http://localhost:8081/api/v1/execute \
    -H "Content-Type: application/json" \
    -d '{"command":"show bgp summary"}'

Open interactive docs: http://localhost:8081/api/v1/docs

Authentication

Ze selects one of three API authentication modes:

Per-user mode has precedence. If at least one user exists, the shared token does not act as a fallback for a failed per-user login.

The per-user source merges the zefs users with system.authentication.user entries from the running config. A config user replaces a zefs user with the same name. Only zefs users that survive this merge keep the zefs recovery profile. A successful login carries its authorization view with the authenticated request. Concurrent requests with the same username cannot replace each other's resolved profiles.

At boot, Ze reads the merged user source once after it populates the config provider. Ze refuses startup before management listeners bind if that read fails. An environment.ssh block is not required for API users or no-BGP AAA.

Each request uses the current accepted authentication generation. A successful reload publishes one generation that adds, changes, or removes API users and authorization policy atomically. The generation includes profile definitions and user-profile assignments. A failed reload keeps the prior credentials and policy. The zefs user list stays the boot snapshot.

Per-user requests keep the authenticated username and the authorizer from that authentication result. Single-token and no-auth requests use a reserved server-injected identity. A valid shared token has write authority. A no-auth request stays read-only, so Ze denies writes before command authorization.

Startup output and remedies

Ze writes one of these exact lines when an API server is configured:

API auth mode: per-user (1 users)

API auth mode: single-token (shared bearer)

warning: API auth mode: NONE (no users, no token) -- set ze.api-server.token or initialize zefs

The per-user count includes surviving zefs users and config users. To leave single-token or NONE mode, add a config user or initialize zefs. To keep shared credentials, set ze.api-server.token.

REST Endpoints

Command execution

A plugin command registered with Hidden true is absent from /api/v1/commands, as it is from completion, from help, and from the MCP tool list. buildCommandMeta is the one source those surfaces read, so the flag has one meaning everywhere.

POST /api/v1/execute body:

{
  "command": "show bgp rib",
  "params": {"family": "ipv4/unicast"}
}

Response:

{
  "status": "done",
  "data": { ... }
}

Convenience routes

Most convenience routes map to the generic Execute endpoint internally. The refresh row gives the required generic Execute command instead.

Config editing

Sessions are owned by the authenticated user. Another user cannot access a session they did not create (returns 403 Forbidden). Idle sessions expire after 30 minutes.

No-auth REST/gRPC callers cannot create config sessions. Configure a token or per-user authentication for API-driven config changes.

Documentation

The OpenAPI spec is generated lazily on first request so it captures all plugin commands registered during startup. Documentation routes use the same Bearer authentication policy as the API when auth is configured.

gRPC Services

Proto definitions: api/proto/ze.proto, package ze.api.v1.

Enable gRPC:

environment {
    api-server {
        grpc {
            enabled true;
            server { ip 127.0.0.1; port 50051; }
        }
    }
}

Loopback gRPC can run plaintext for local tooling. Non-loopback gRPC listeners must be authenticated and must configure TLS with both tls-cert and tls-key.

ZeService

Generic command execution and discovery.

CommandResponse.data is JSON-encoded bytes for identical content with REST.

ZeConfigService

Typed config session management (same semantics as REST config sessions).

gRPC authentication

Pass the same Bearer username:password or Bearer <token> as REST, via the authorization metadata key:

metadata = [('authorization', 'Bearer alice:password123')]
stub.Execute(CommandRequest(command='show bgp summary'), metadata=metadata)

gRPC reflection

Reflection is enabled by default. Discover the schema with grpcurl on a plaintext loopback listener:

grpcurl -plaintext localhost:50051 list
grpcurl -plaintext localhost:50051 describe ze.api.v1.ZeService
grpcurl -plaintext -d '{"command":"show bgp summary"}' \
    -H "authorization: Bearer alice:password123" \
    localhost:50051 ze.api.v1.ZeService/Execute

TLS

Configure TLS via YANG before binding gRPC outside loopback:

environment {
    api-server {
        grpc {
            enabled true;
            tls-cert "/etc/ze/server.pem";
            tls-key "/etc/ze/server.key";
        }
    }
}

Both fields must be set together. Minimum TLS version is 1.2. Startup fails if an authenticated non-loopback gRPC listener is configured without TLS.

CORS

For browser-based clients, set an allowed origin:

environment {
    api-server {
        rest {
            enabled true;
            cors-origin "https://dashboard.example.com";
        }
    }
}

Preflight OPTIONS requests are handled automatically.

Environment Variables

Precedence: env > YANG config. Values set in env override YANG.

Input Validation

Both transports validate command input against shell injection:

• URL path segments (peer name, RIB family) reject whitespace and control chars
• Execute params map keys and values reject whitespace
• Config session IDs must match the hex format from EnterSession

These checks prevent command tokenizer confusion when user input flows into dispatcher command strings.

Differences Between Transports

The transports are functionally equivalent. Pick based on client needs: