REST API

HTTP API를 통해 장치 데이터를 전송하고 명령을 보낼 수 있습니다.

인증

모든 API는 X-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: 장치 ID
• data: 서버에 전송할 데이터
• _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"
}

커맨드 API

서버에서 장치로 커맨드를 전송합니다.

요청 본문

{
  "deviceId": "sensor-001",
  "command": "set_interval 30"
}

• deviceId: 명령을 받을 장치 ID
• command: 장치에 전송할 명령 문자열

커맨드 예시

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)

데이터 조회

파일/명령

한도 초과 처리 예시

Bulk Import API

대량의 과거 데이터를 한 번에 Import할 수 있는 관리자 전용 API입니다.

특징

• Rate Limit 없음
• 파서 처리 없음 (데이터가 그대로 저장됨)
• 규칙 트리거 없음
• 요청 당 최대 10,000건

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 밀리초. 생략 시 서버 수신 시간 사용

요청 예시

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"
    }
  ]
}

다음 단계