HTTP API를 통해 장치 데이터를 전송하고 명령을 보낼 수 있습니다.
이 문서는 장치 연동에 필요한 기본 API를 간략히 설명합니다. 전체 API 명세는 Swagger 문서에서 확인하세요.
인증
모든 API는 X-API-Key 헤더로 인증합니다.
| 헤더 | 값 | 설명 |
|---|---|---|
X-API-Key | your-api-key | 그룹 API 키 |
Group ID와 API Key 확인 방법
| 계정 레벨 | Group ID / API Key 위치 |
|---|---|
관리자 | 그룹 페이지에서 각 그룹의 인증 정보 |
매니저 | 헤더 우측의 프로필 메뉴 > 내 그룹 인증 정보 |
데이터 API
장치 데이터를 서버로 전송합니다. deviceId가 서버에 등록되지 않은 경우 자동으로 장치가 생성됩니다.
요청 본문
{
"deviceId": "sensor-001",
"data": {
"temperature": 25.5,
"humidity": 60
},
"_timestamp": "2025-01-08T12:00:00.000Z"
}deviceId: 장치 IDdata: 서버에 전송할 데이터_timestamp: (선택) 장치가 보고하는 측정 시간. 데이터 측정(생성) 시간과 서버 수신 시간이 다를 경우에 사용합니다. 오랜 시간이 경과한 데이터를 측정 시간에 맞도록 서버에 저장할 수 있습니다. ISO 8601 형식 또는 Unix 밀리초 타임스탬프. 생략 시 서버 수신 시간이 사용됩니다. 과거 시간은 제한 없이 허용되지만, 서버 시간보다 5분 이상 미래인 값은 장치 시계 오류로 간주하여 무시하고 서버 수신 시간을 사용합니다.
요청 예시
curl -X POST "https://your-server/api/v1/data" \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_API_KEY" \
-d '{
"deviceId": "sensor-001",
"data": {
"temperature": 25.5,
"humidity": 60
}
}'응답
{
"deviceId": "sensor-001",
"timestamp": "2025-01-08T12:00:00.000Z"
}파일 첨부 (multipart)
이미지, 동영상 같은 파일은 같은 주소로 multipart/form-data 요청을 보내 데이터와 함께 올립니다. 파일을 담은 폼 필드 이름이 그대로 데이터 필드 이름이 되고, 그 필드에 저장된 파일의 경로가 기록됩니다.
curl -X POST "https://your-server/api/v1/data" \
-H "X-API-Key: YOUR_API_KEY" \
-F "deviceId=camera-001" \
-F 'data={"event": "motion"}' \
-F "video=@clip.mp4;type=video/mp4" \
-F "snapshot=@snapshot.jpg;type=image/jpeg"deviceId: 장치 ID (필수)data: (선택) 함께 저장할 데이터. JSON 객체를 문자열로 보냅니다._timestamp: (선택) JSON 요청과 같습니다.- 파일: 필드 이름은 자유롭게 정하되, 한 요청에서 같은 필드 이름은 한 번만 쓸 수 있습니다. 위 예시는
video와snapshot필드에 각각 파일이 저장됩니다.
파일 종류와 표시 형태
| 종류 | 파일 이름 확장자 | 데이터 조회 시 표시 형태 |
|---|---|---|
| 이미지 | jpg, jpeg, png, gif, webp, svg, bmp, ico, avif, heic | 썸네일 갤러리 (누르면 이미지 뷰어) |
| 동영상 | mp4, m4v, webm, mov, ogv | 동영상 플레이어와 목록 |
| 파일 | 그 밖의 확장자(pdf, csv, zip 등) | 파일 목록 (새 탭 열기·다운로드) |
- 파일 이름에 확장자를 붙여 보내세요. 데이터 조회 시 표시 형태는 이 확장자로 정해지며, 대소문자는 구분하지 않습니다.
- 확장자가 없는 파일일 경우, Content-Type으로 표시 형태가 정해집니다. 이때 알아보는 형식은 image/jpeg, image/png, image/gif, image/webp, video/mp4, application/pdf이고, 나머지는 일반 파일이 됩니다.
- 장치 데이터 조회 시 표시 형태는 필드의 최신 값에 의해 결정되므로 한 필드에는 같은 종류의 파일을 보내세요.
- 대시보드에서는 이미지 필드를 이미지 위젯, 동영상 필드를 동영상 위젯에서 고를 수 있습니다.
동영상 썸네일
동영상과 같은 요청에 {동영상 필드}_thumbnail 이름으로 이미지를 함께 보내면, 그 이미지가 영상의 썸네일이 됩니다.
curl -X POST "https://your-server/api/v1/data" \
-H "X-API-Key: YOUR_API_KEY" \
-F "deviceId=camera-001" \
-F "video=@clip.mp4;type=video/mp4" \
-F "video_thumbnail=@clip.jpg;type=image/jpeg"- 썸네일은 같은 요청에 함께 보낸 영상에만 연결됩니다. 썸네일 없이 보낸 영상은 동영상 아이콘으로 표시됩니다.
- 썸네일은 장치 데이터 상세 페이지, 동영상 플레이어 및 위젯 등에서 사용됩니다.
- mp4·m4v·mov 영상은 플레이어와 동영상 목록에 재생 길이, 해상도, 코덱이 함께 표시됩니다. (파일 헤더 정보 참조)
- 동영상은 대부분의 브라우저에서 재생되는 H.264 MP4를 권장합니다. H.265(HEVC) 등은 브라우저에 따라 재생되지 않을 수 있습니다.
- 파일 하나는 기본 100MB까지 올릴 수 있고, 넘으면 413 오류가 납니다.
- 응답에는 파일 URL이 포함되지 않습니다. 저장된 파일은 웹 화면이나 장치 데이터 조회 API에서 확인합니다.
커맨드 API
서버에서 장치로 커맨드를 전송합니다.
장치가 명령을 받기 위해선 MQTT를 사용해야 합니다. MQTT 사용법
요청 본문
{
"deviceId": "sensor-001",
"command": "set_interval 30"
}deviceId: 명령을 받을 장치 IDcommand: 장치에 전송할 명령 문자열
커맨드 예시
명령 형식은 자유롭습니다. 장치가 파싱할 수 있는 어떤 문자열이든 가능합니다.
set_interval 30{"action": "update", "value": 100}요청 예시
curl -X POST "https://your-server/api/v1/command" \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_API_KEY" \
-d '{
"deviceId": "sensor-001",
"command": "set_interval 30"
}'응답
{
"deviceId": "sensor-001",
"command": "set_interval 30"
}Rate Limit
각 외부 API 엔드포인트별 한도와 적용 단위입니다. 한도 초과 시 429 Too Many Requests와 Retry-After 헤더(초 단위 대기)가 반환됩니다.
데이터 수집 (Ingestion)
| 메서드 | 경로 | 한도 | 단위 |
|---|---|---|---|
| POST | /api/v1/data | 60회/분 | 장치당 |
| POST | /api/v1/data (배치) | 30회/분 | API 키당 |
| POST | /api/v1/data/no-rules | 60회/분 | 장치당 |
| POST | /api/v1/data/no-rules/batch | 30회/분 | API 키당 |
데이터 조회
| 메서드 | 경로 | 한도 | 단위 |
|---|---|---|---|
| GET | /api/v1/devices | 60회/분 | API 키당 |
| GET | /api/v1/devices/{id} | 60회/분 | API 키당 |
| GET | /api/v1/devices/{id}/data | 10회/분 | API 키당 |
| GET | /api/v1/devices/{id}/data/chart | 10회/분 | API 키당 |
| GET | /api/v1/group | 60회/분 | API 키당 |
| GET | /api/v1/alerts/* | 60회/분 | API 키당 |
파일/명령
| 메서드 | 경로 | 한도 | 단위 | 비고 |
|---|---|---|---|---|
| GET | /api/v1/files/* | 300회/분 | 장치당 | 한 장치 데이터 일괄 다운로드용으로 여유롭게 |
| POST | /api/v1/command | 60회/분 | 장치당 |
한도 초과 처리 예시
단위 의미
- 장치당: 같은 디바이스에 대한 요청을 분당 N회까지. 다른 디바이스는 별도 카운트.
- API 키당: 한 그룹(=한 API 키)이 통째로 분당 N회까지.
Swagger UI의 각 엔드포인트 상세 화면에서 429 Rate limit exceeded 응답으로 같은 정보를 확인할 수 있습니다.
Bulk Import API
대량의 과거 데이터를 한 번에 Import할 수 있는 관리자 전용 API입니다.
이 API는 관리자가 발급한 Admin Token이 필요합니다.
Admin Token은 관리 > 보안 페이지에서 발급할 수 있습니다.
특징
- Rate Limit 없음
- 파서 처리 없음 (데이터가 그대로 저장됨)
- 규칙 트리거 없음
- 요청 당 최대 10,000건
Admin Token 인증
| 헤더 | 값 | 설명 |
|---|---|---|
X-Admin-Token | adm_xxxxx... | Admin Token |
요청 본문
{
"groupId": "group-uuid",
"deviceId": "sensor-001",
"records": [
{
"data": { "temperature": 25.5, "humidity": 60 },
"timestamp": "2025-01-01T00:00:00Z"
},
{
"data": { "temperature": 26.0, "humidity": 58 },
"timestamp": "2025-01-01T00:01:00Z"
}
]
}groupId: 대상 그룹 UUID (관리 > 그룹또는인증 정보에서 확인)deviceId: 장치 ID (미등록 시 자동 생성)records: 데이터 배열 (최대 10,000건)data: 저장할 데이터timestamp: (선택) ISO 8601 형식 또는 Unix 밀리초. 생략 시 서버 수신 시간 사용
장치 API와 달리 Bulk Import는 잘못된 timestamp를 서버 시간으로 대체하지 않습니다.
서버 시간보다 5분 이상 미래이거나 형식이 잘못된 레코드는 거부되며, 응답의 errors에
해당 레코드의 인덱스와 함께 보고됩니다. 같은 요청의 나머지 레코드는 정상적으로 저장됩니다.
과거 시간은 제한 없이 허용됩니다.
요청 예시
curl -X POST "https://your-server/api/v1/data/bulk-import" \
-H "Content-Type: application/json" \
-H "X-Admin-Token: adm_your_token_here" \
-d '{
"groupId": "group-uuid",
"deviceId": "sensor-001",
"records": [
{ "data": { "temperature": 25.5 }, "timestamp": "2025-01-01T00:00:00Z" },
{ "data": { "temperature": 26.0 }, "timestamp": "2025-01-01T00:01:00Z" }
]
}'응답
{
"total": 2,
"success": 2,
"failed": 0,
"errors": []
}일부 레코드가 거부된 경우에도 상태 코드는 201이며, errors에서 거부 사유를 확인할 수 있습니다.
{
"total": 3,
"success": 2,
"failed": 1,
"errors": [
{
"index": 1,
"error": "Timestamp is in the future (2031-01-01T00:00:00.000Z): must not be more than 5 minutes ahead of server time"
}
]
}10,000건 이상의 데이터를 Import할 경우, 여러 번의 요청으로 나누어 전송하세요.
