VDAS Cloud API 는 클라우드에 연결된 VDAS 에스프레소 머신의 샷 기록·라이브 텔레메트리·머신 상태를 개발자에게 읽기로 열고, 계약에 따라 허용 목록(화이트리스트)의 설정을 원격으로 쓰게 하는 HTTP API 예요. 이 문서는 미리보기 설계 초안이에요. 실제 서버에는 아직 이 엔드포인트가 없어요.
범위
영역
읽기
쓰기
상태
머신 · 펌웨어 상태
GET /v1/public/machines
—
초안
샷 기록 (곡선 포함)
GET /v1/public/shots
—
초안
라이브 텔레메트리
GET …/telemetry/stream (SSE)
—
초안
원격 설정 (허용 목록 7종)
GET …/settings
PATCH …/settings (OAuth2)
초안 · 안전 심사 뒤
웹훅
GET /v1/public/webhooks
POST /v1/public/webhooks
초안
API 키
GET /v1/public/api-keys
POST · DELETE
초안
원격 추출 시작/정지
—
—
검토 중 (계약·안전 심사 선행)
이렇게 만들어요
머신이 보고한 값만 믿어요. 서버는 "밀었다"가 아니라 머신이 읽어서 올린 값을 저장해요. 쓰기 응답도 보드가 다시 읽은 값이에요.
안전 한계는 보드 안에서만 지켜요. 과열 래치·최대 압력·연속 출수 시간 같은 안전 한계와 보일러 온도·추출 파라미터·펌웨어 설정은 원격 쓰기 경로가 없고 열 계획도 없어요 (안전 경계).
허용 목록에 없으면 막혀요. 목록 밖 키는 경로 자체가 없어 403 으로 끝나요. 범위 밖 값은 클램프 없이 400.
주소를 따로 둬요. 공개 API 는 /v1/public/… 아래에만 있어요. 기기 대면 API(/v1/devices/*)와 기술자 어드민(/v1/admin/*)과 겹치지 않아요.
버전은 주소에 적어요. 깨지는 변경은 /v2/. 필드 추가는 깨지는 변경이 아니에요 — 클라이언트는 모르는 필드를 무시해야 해요.
기본 정보
항목
값
Base URL
https://api.vidas.example/v1/public (예시 — 실제 호스트는 정식 출시 때 공지)
형식
JSON (UTF-8) · 시각은 RFC 3339 UTC · 단위는 필드명에 (_bar, _ml_s, _c, _g, _deg)
# 1. 머신 목록
curl https://api.vidas.example/v1/public/machines \
-H "Authorization: Bearer vdas_pk_test_…"
# 2. 그 머신의 최근 샷 10개
curl "https://api.vidas.example/v1/public/shots?machine=VDAS-PRO1G-2644-9999&limit=10" \
-H "Authorization: Bearer vdas_pk_test_…"
# 3. 라이브 텔레메트리 (SSE)
curl -N https://api.vidas.example/v1/public/machines/VDAS-PRO1G-2644-9999/telemetry/stream \
-H "Authorization: Bearer vdas_pk_test_…"
VDAS Cloud API opens shot records, live telemetry and machine status of cloud-connected VDAS espresso machines to developers for reading, and lets contracts enable remote writes of an allow-list of settings. This wiki is the preview design draft — the endpoints do not exist on the production server yet.
Scope
Area
Read
Write
Status
Machines · firmware
GET /v1/public/machines
—
draft
Shots (with curves)
GET /v1/public/shots
—
draft
Live telemetry
GET …/telemetry/stream (SSE)
—
draft
Remote settings (7 allow-listed keys)
GET …/settings
PATCH …/settings (OAuth2)
draft · after safety review
Webhooks
GET /v1/public/webhooks
POST /v1/public/webhooks
draft
Remote start/stop
—
—
under review
Principles
Only device-reported values are canonical. Write responses carry the value the board read back.
Safety limits live on the board. Safety limits, boiler setpoints, extraction parameters and firmware settings have no remote write path and none is planned.
The allow-list is fail-closed. Keys outside it have no route (403); out-of-range values are rejected (400), never clamped.
Separate namespace. Everything public lives under /v1/public/…, apart from device (/v1/devices/*) and technician admin (/v1/admin/*) APIs.
Versions in the path. Breaking changes go to /v2/; added fields are not breaking.