API 总览

EnerOS 提供四种 API 接口，满足不同场景的接入需求。所有 API 均通过 eneros-api 与 eneros-graphql crate 暴露，并由 eneros-gateway 进行统一鉴权、限流与安全审计。无论选择哪种协议，底层共享同一套内核系统调用，因此数据一致性、约束校验、审计日志均得到保证。

API 类型对比

EnerOS 提供四种 API 接口，分别对应不同的接入场景与通信模型：

选型决策树

是否需要服务端主动推送？
├── 否 → 是否需要灵活字段选取或跨资源聚合？
│       ├── 是 → GraphQL
│       └── 否 → REST
└── 是 → 是否需要客户端向服务端发送指令？
        ├── 是（双向） → WebSocket
        └── 否（单向） → 是否运行在浏览器中？
                ├── 是 → SSE（自动重连）
                └── 否 → WebSocket（更高效）

并发与资源占用

基础信息

Base URL

EnerOS API 的根 URL 取决于部署模式：

各协议端点：

生产环境强制启用 HTTPS / WSS，由 eneros-trust 签发证书。

通用约定

鉴权方式

EnerOS 支持三种鉴权方式，可单独或组合使用：

1. Bearer Token

最常用的鉴权方式。Token 由 eneros-trust 签发，包含租户、角色、过期时间与权限范围。Token 默认有效期 1 小时，可通过刷新机制续期。

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

2. mTLS 双向认证

生产环境推荐使用。客户端与网关互相验证 X.509 证书，由内部 CA 签发。mTLS 可与 Bearer Token 叠加使用，实现双重校验。

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

3. API Key（仅限服务间调用）

用于内部服务调用的长期凭证，不能用于面向终端用户的场景。API Key 绑定到特定服务账号，权限范围受限。

X-API-Key: sk-internal-xxxxxxxxxxxxxxxxxxxx

鉴权方式对比

通用请求头

通用响应格式

成功响应

所有 REST 成功响应均为 JSON，顶层字段约定如下：

示例：

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

错误响应

错误响应统一格式：

示例：

{
  "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#错误码"
  },
  "request_id": "req_20260706_8f3a2b"
}

错误码总表

EnerOS 错误码分为五类：客户端错误（4xx）、服务端错误（5xx）、网关错误、安全错误、业务错误。

客户端错误（4xx）

服务端错误（5xx）

安全错误

业务错误

版本管理

EnerOS API 采用 URL 路径版本 + 语义化版本双重策略：

详细策略见 版本管理。

限流策略

EnerOS 采用分层限流，详见 限流与配额：

所有限流响应都附带 X-RateLimit-* 响应头，便于客户端自适应降速。

SDK 列表

EnerOS 官方提供以下 SDK，封装鉴权、重试、序列化等通用逻辑：

SDK 选型建议

// Rust SDK 示例
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 示例
from eneros_sdk import ApiClient

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

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

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

快速验证

使用 cURL 快速验证 API 可用性：

# 1. 健康检查（无需认证）
curl http://localhost:8080/api/v1/health

# 2. 获取 Token（开发环境）
curl -X POST http://localhost:8080/api/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin"}'

# 3. 获取网络列表
curl -H "Authorization: Bearer <token>" \
  http://localhost:8080/api/v1/networks

# 4. 创建 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 查询
curl -X POST http://localhost:8080/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{"query":"{ networks { id name } }"}'

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

通用响应字段枚举

资源状态枚举

严重级别枚举

相关文档

• REST API — 完整端点文档
• GraphQL — Schema 与查询示例
• WebSocket — 实时事件流协议
• SSE 实时推送 — 单向订阅端点
• 限流与配额 — 速率限制策略
• 版本管理 — API 版本演进