REST API (Server)

REST API dành cho các hệ thống bên ngoài muốn tích hợp với VieLang IoT: quản lý thiết bị, đọc telemetry, tạo alarm, quản lý người dùng...

Khác với HTTP Device API dành cho thiết bị, REST API này dành cho ứng dụng server-to-server.

Swagger UI

Xem và thử tất cả endpoints tại:

http://localhost:8080/swagger-ui

Swagger cung cấp:

Danh sách đầy đủ endpoints
Request/response schema
Giao diện test trực tiếp (cần đăng nhập)

Xác thực

Lấy JWT Token

POST /api/auth/login
Content-Type: application/json

{
  "username": "tenant@vielang.io",
  "password": "tenant"
}

# Response:
{
  "token": "eyJhbGciOiJIUzI1NiJ9...",
  "refreshToken": "eyJhbGciOiJIUzI1NiJ9..."
}

Access Token hết hạn sau 2.5 giờ
Refresh Token hết hạn sau 7 ngày

Dùng JWT Token

Thêm vào header của mọi request:

curl -H "X-Authorization: Bearer YOUR_JWT_TOKEN" ...
# Hoặc
curl -H "Authorization: Bearer YOUR_JWT_TOKEN" ...

Làm mới Token

POST /api/auth/token
Content-Type: application/json

{ "refreshToken": "YOUR_REFRESH_TOKEN" }

# Response:
{ "token": "NEW_ACCESS_TOKEN", "refreshToken": "NEW_REFRESH_TOKEN" }

Devices API

Lấy danh sách thiết bị

GET /api/tenant/devices?pageSize=20&page=0&textSearch=sensor
Authorization: Bearer {JWT}

# Response:
{
  "data": [
    {
      "id": { "id": "device-uuid", "entityType": "DEVICE" },
      "createdTime": 1735000000000,
      "name": "Sensor-01",
      "type": "Temperature Sensor",
      "tenantId": { "id": "tenant-uuid", "entityType": "TENANT" }
    }
  ],
  "totalPages": 3,
  "totalElements": 57,
  "hasNext": true
}

Tạo thiết bị

POST /api/device
Authorization: Bearer {JWT}
Content-Type: application/json

{
  "name": "Sensor-01",
  "type": "Temperature Sensor",
  "additionalInfo": { "description": "Cảm biến phòng máy chủ" }
}

# Response: { "id": {...}, "name": "Sensor-01", ... }

Lấy chi tiết thiết bị

GET /api/device/{deviceId}
Authorization: Bearer {JWT}

Xóa thiết bị

DELETE /api/device/{deviceId}
Authorization: Bearer {JWT}

Telemetry API

Lấy giá trị mới nhất

GET /api/plugins/telemetry/DEVICE/{deviceId}/values/timeseries
  ?keys=temperature,humidity
Authorization: Bearer {JWT}

# Response:
{
  "temperature": [{"ts": 1735000000000, "value": "25.5"}],
  "humidity":    [{"ts": 1735000000000, "value": "68"}]
}

Lấy lịch sử

GET /api/plugins/telemetry/DEVICE/{deviceId}/values/timeseries
  ?keys=temperature
  &startTs=1733000000000
  &endTs=1735000000000
  &interval=3600000
  &agg=AVG
  &limit=168
Authorization: Bearer {JWT}

Ghi telemetry từ server

POST /api/plugins/telemetry/DEVICE/{deviceId}/timeseries/SERVER_SCOPE
Authorization: Bearer {JWT}
Content-Type: application/json

{ "temperature": 25.5, "humidity": 68 }

Alarms API

Lấy danh sách alarm

GET /api/alarms
  ?pageSize=20&page=0
  &statusList=ACTIVE_UNACK
  &severityList=CRITICAL,MAJOR
  &sortProperty=createdTime&sortOrder=DESC
Authorization: Bearer {JWT}

Tạo alarm thủ công

POST /api/alarm
Authorization: Bearer {JWT}
Content-Type: application/json

{
  "originator": { "id": "device-uuid", "entityType": "DEVICE" },
  "type": "Manual Test Alarm",
  "severity": "WARNING",
  "status": "ACTIVE_UNACK",
  "startTs": 1735000000000
}

Assets API

# Tạo asset
POST /api/asset
Authorization: Bearer {JWT}
Content-Type: application/json

{
  "name": "Building A",
  "type": "building"
}

# Lấy danh sách
GET /api/tenant/assets?pageSize=20&page=0
Authorization: Bearer {JWT}

Users API

# Lấy danh sách users
GET /api/users?pageSize=20&page=0
Authorization: Bearer {JWT}

# Tạo user mới
POST /api/user
Authorization: Bearer {JWT}
Content-Type: application/json

{
  "email": "operator@factory.vn",
  "authority": "CUSTOMER_USER",
  "customerId": { "id": "customer-uuid", "entityType": "CUSTOMER" },
  "firstName": "Nguyễn",
  "lastName": "Văn An"
}

Pagination

Tất cả danh sách đều hỗ trợ pagination:

?pageSize=20   ← Số phần tử mỗi trang (tối đa 1000)
&page=0        ← Trang hiện tại (bắt đầu từ 0)
&sortProperty=createdTime
&sortOrder=DESC
&textSearch=keyword

Response:

{
  "data": [...],
  "totalPages": 5,
  "totalElements": 98,
  "hasNext": true
}

SDK & Client Libraries

Python

pip install tb-rest-client

from tb_rest_client.rest_client_ce import RestClientCE

client = RestClientCE("http://localhost:8080")
client.login(username="tenant@vielang.io", password="tenant")

devices = client.get_tenant_devices(page_size=20, page=0)

JavaScript / TypeScript

import axios from "axios"

const api = axios.create({ baseURL: "http://localhost:8080" })

const { data } = await api.post("/api/auth/login", {
  username: "tenant@vielang.io",
  password: "tenant",
})

api.defaults.headers.common["X-Authorization"] = `Bearer ${data.token}`

const devices = await api.get("/api/tenant/devices?pageSize=20&page=0")