API Overview

EnerOS provides four API interfaces to meet access needs in different scenarios. All APIs are exposed through the eneros-api and eneros-graphql crates, and unified authentication, rate limiting, and security audit are performed by eneros-gateway. Regardless of which protocol is chosen, the underlying layer shares the same set of kernel system calls, ensuring data consistency, constraint validation, and audit logs.

API Type Comparison

EnerOS provides four API interfaces, corresponding to different access scenarios and communication models:

Selection Decision Tree

Does the server need to push proactively?
├── No → Need flexible field selection or cross-resource aggregation?
│       ├── Yes → GraphQL
│       └── No → REST
└── Yes → Does the client need to send commands to the server?
        ├── Yes (bidirectional) → WebSocket
        └── No (one-way) → Running in a browser?
                ├── Yes → SSE (auto reconnect)
                └── No → WebSocket (more efficient)

Concurrency and Resource Usage

Basic Information

Base URL

The root URL of the EnerOS API depends on the deployment mode:

Protocol endpoints:

Production environments enforce HTTPS / WSS, with certificates issued by eneros-trust.

Common Conventions

Authentication Methods

EnerOS supports three authentication methods, which can be used individually or in combination:

1. Bearer Token

The most commonly used authentication method. Tokens are issued by eneros-trust and contain tenant, role, expiration time, and permission scope. Tokens default to 1-hour validity and can be renewed through the refresh mechanism.

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

2. mTLS Mutual Authentication

Recommended for production environments. Client and gateway mutually verify X.509 certificates, issued by internal CA. mTLS can be stacked with Bearer Token for dual verification.

curl --cert client.crt --key client.key --cacert ca.crt \
  https://api.example.com/api/v1/networks

3. API Key (Internal Service Calls Only)

Long-term credentials for internal service calls, cannot be used for end-user scenarios. API Keys are bound to specific service accounts with restricted permission scope.

X-API-Key: sk-internal-xxxxxxxxxxxxxxxxxxxx

Authentication Method Comparison

Common Request Headers

Common Response Format

Success Response

All REST success responses are JSON, with top-level fields as follows:

Example:

{
  "data": {
    "id": "net_8f3a2b",
    "name": "IEEE-14"
  },
  "meta": {
    "version": "v1",
    "deprecated": false
  },
  "request_id": "req_20260706_8f3a2b",
  "timestamp": "2026-07-06T08:30:00Z"
}

Error Response

Unified error response format:

Example:

{
  "error": {
    "code": "CONSTRAINT_VIOLATION",
    "message": "Branch 1-2 overload: 105% of limit",
    "details": {
      "branch_id": "1-2",
      "loading": 1.05,
      "limit": 1.0
    },
    "trace_id": "trace_abc123",
    "doc_url": "https://docs.openeneros.com/api-reference/rest#error-codes"
  },
  "request_id": "req_20260706_8f3a2b"
}

Error Code Table

EnerOS error codes are divided into five categories: client errors (4xx), server errors (5xx), gateway errors, security errors, and business errors.

Client Errors (4xx)

Server Errors (5xx)

Security Errors

Business Errors

Version Management

EnerOS API adopts a dual strategy of URL path versioning + semantic versioning:

See Version Management for detailed strategy.

Rate Limiting Strategy

EnerOS adopts layered rate limiting, see Rate Limiting and Quota:

All rate limit responses include X-RateLimit-* response headers for client adaptive rate reduction.

SDK List

EnerOS officially provides the following SDKs, encapsulating common logic such as authentication, retry, and serialization:

SDK Selection Suggestion

// Rust SDK example
use eneros_sdk::ApiClient;

let client = ApiClient::builder()
    .endpoint("http://localhost:8080")
    .api_version("v1")
    .token("<bearer-token>")
    .build()?;

let networks = client.networks().list().await?;

# Python SDK example
from eneros_sdk import ApiClient

client = ApiClient(
    endpoint="http://localhost:8080",
    api_version="v1",
    token="<bearer-token>",
)
networks = client.networks.list()

// JavaScript SDK example
import { ApiClient } from '@eneros/sdk';

const client = new ApiClient({
  endpoint: 'http://localhost:8080',
  apiVersion: 'v1',
  token: '<bearer-token>',
});
const networks = await client.networks.list();

Quick Verification

Use cURL to quickly verify API availability:

# 1. Health check (no authentication required)
curl http://localhost:8080/api/v1/health

# 2. Get Token (development environment)
curl -X POST http://localhost:8080/api/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin"}'

# 3. Get network list
curl -H "Authorization: Bearer <token>" \
  http://localhost:8080/api/v1/networks

# 4. Create Agent
curl -X POST http://localhost:8080/api/v1/agents \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"type":"dispatch","config":{}}'

# 5. GraphQL query
curl -X POST http://localhost:8080/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{"query":"{ networks { id name } }"}'

# 6. SSE subscribe to alerts
curl -N -H "Authorization: Bearer <token>" \
  "http://localhost:8080/api/v1/events/stream?topics=alarm&severity=critical"

Common Response Field Enums

Resource Status Enums

Severity Level Enums

Related Documentation

• REST API — Complete endpoint documentation
• GraphQL — Schema and query examples
• WebSocket — Real-time event stream protocol
• SSE Real-time Push — One-way subscription endpoint
• Rate Limiting and Quota — Rate limiting strategy
• Version Management — API version evolution