Open API Reference – Legacy – CoXlab Inc. (주)콕스랩

OpenAPI Version :

1. Introduction

IoT.own은 타 시스템에서 연동하기 위하여 RESTful API를 제공합니다.
API를 사용하려면 토큰이 필요하며 IoT.own에 로그인 후 Open API 토큰 메뉴에서 얻을 수 있습니다. (토큰 얻기)

<주의 사항> 2019년 1월 29일 이후 배포되는 서버를 사용하시는 경우, legacy API를 지원하지 않습니다. 설치 버전의 날짜는 로그인 화면 하단에서 확인가능합니다. 2019년 1월 29일 이후 설치된 서버의 경우 반드시 API 1.0 이후 버전을 사용해주십시오.

3. Error Descriptions

모든 API는 errorCode와 errorStr을 반환합니다. errorCode가 0일 경우 성공, 0이 아닐 경우 에러를 의미합니다.

에러코드 (`errorCode`)	설명 (`errorStr`)
-1	서버 정검 혹은 장애
-2	`token` 파라메터 누락
-3	`token`의 만료 혹은 잘못된 token
-10	`gateway_id` 파라메터 누락
-11	등록되지 않은 `gateway_id`
-20	`node_id` 파라메터 누락
-21	등록되지 않은 `node_id`
-31	파라메터 오류. 시간 정보가 UTC 포멧이 아닐 경우
-40	`URL` 파라메터 누락
-50	커맨드 파라메터 누락
-51	커맨드의 `type` 파라메터 누락
-52	커맨드의 `type` 파라메터가 `"hex"` 혹은 `"string"`이 아닌 경우
-53	커맨드 내용에 오류가 있는 경우. 예) hex type인데 hex string이 아닌 경우
-60	LoRa 서버 API 호출 실패
-61	LoRa 서버 API 에러

(주의사항) 시간 표기법
API에서 리턴되는 모든 시간 정보는 표준 UTC시간이므로 로컬지역에 맞게 변형해서 사용해야 합니다.

4. API Descriptions

4-1. GET gateway/get-list

URL: https://town.coxlab.kr/api/gateway/get-list

이 API를 통해서 IoT.own과 연동된 게이트웨이 목록을 가져올 수 있습니다.

Parameter

token: API 토큰

Response

list[]: 게이트웨이 객체 배열
gateway_id: 게이트웨이 아이디
gateway_eui: 게이트웨이 EUI
gateway_type: IoT.own 등록시 사용자가 임의 입력하는 정보
gateway_desc: IoT.own 등록시 사용자가 임의 입력하는 정보
created_at: IoT.own에 등록된 시간(UTC)
recent_act (optional): 게이트웨이가 마지막으로 동작한 시간(UTC)
bootup_time (optional): 마지막으로 부팅된 시간(UTC). 부팅 메세지가 누락된 경우, 필드가 없을 수 있음.
latitude (optional): 위도
longitude (optional): 경도
altitude (optional): 고도

Example

https://town.coxlab.kr/api/gateway/get-list?token=00112233445566778899aabbccddeeff00112233445566778899aabbccddeeff

{
  "list":[
    {
      "created_at":"2016-05-30T05:54:59.995Z",
      "gateway_desc":"GW002설명",
      "gateway_type":"GW002타입",
      "gateway_id":"GW002"
    },
    {
      "created_at":"2016-05-30T05:27:14.808Z",
      "gateway_desc":"GW001설명",
      "gateway_type":"GW001타입",
      "gateway_id":"GW001"
    }
  ],
  "errorCode":0,
  "errorStr":""
}

4-2. GET gateway/get-info

URL: https://town.coxlab.kr/api/gateway/get-info

이 API를 통해서 IoT.own과 연동된 특정 게이트웨이의 정보를 가져올 수 있습니다.

Parameters

token: API 토큰
gateway_id: 게이트웨이 아이디

Response

gateway: 게이트웨이 객체
gateway_id: 게이트웨이 아이디
gateway_eui: 게이트웨이 EUI
gateway_type: IoT.own 등록시 사용자가 임의 입력하는 정보
gateway_desc: IoT.own 등록시 사용자가 임의 입력하는 정보
created_at: IoT.own에 등록된 시간(UTC)
recent_act (optional): 게이트웨이가 마지막으로 동작한 시간(UTC)
bootup_time (optional): 마지막으로 부팅된 시간(UTC). 부팅 메세지가 누락된 경우, 필드가 없을 수 있음.
latitude (optional): 위도. 만약 Gateway Management 페이지에서 별도로 설정한 좌표 정보가 있거나 게이트웨이로부터 실시간 위치 정보가 제공되는 경우에만 이 필드가 존재합니다.
longitude (optional): 경도. 만약 Gateway Management 페이지에서 별도로 설정한 좌표 정보가 있거나 게이트웨이로부터 실시간 위치 정보가 제공되는 경우에만 이 필드가 존재합니다.
altitude (optional): 고도. 만약 Gateway Management 페이지에서 별도로 설정한 좌표 정보가 있거나 게이트웨이로부터 실시간 위치 정보가 제공되는 경우에만 이 필드가 존재합니다.

Example

https://town.coxlab.kr/api/gateway/get-info?token=00112233445566778899aabbccddeeff00112233445566778899aabbccddeeff&gateway_id=GW001

{
  "gateway":{
    "bootup_time":"2016-06-01T07:03:21.445Z",
    "created_at":"2016-05-30T05:27:14.808Z",
    "gateway_desc":"GW001설명",
    "gateway_id":"GW001"
    "gateway_type":"GW001종류",
    "gateway_eui":"AA555A0000000101",
    "recent_act":"2016-06-04T02:11:16.902Z",
    "latitude":"36.49197",
    "longitude":"127.25633",
    "altitude":"10.5"
  },
  "errorCode":0,
  "errorStr":""
}

4-3. GET gateway/connected-node-list

URL: https://town.coxlab.kr/api/gateway/connected-node-list

이 API를 통해서 IoT.own과 연동된 특정 게이트웨이의 하위 노드 목록을 가져올 수 있습니다.

Parameters

token: API 토큰
gateway_id: 게이트웨이 아이디

Response

list[]: 게이트웨이에 연결된 노드 리스트 객체
node_id: 노드 아이디

Example

https://town.coxlab.kr/api/gateway/connected-node-list?token=00112233445566778899aabbccddeeff00112233445566778899aabbccddeeff&gateway_id=GW001

{
  "list" : [
    {"node_id" : "N001"},
    {"node_id" : "N002"},
    {"node_id" : "N003"}
  ],
  "errorCode":0,
  "errorStr":""
}

4-4. GET node/get-list

URL: https://town.coxlab.kr/api/node/get-list

이 API를 통해서 IoT.own에 등록된 노드 목록을 가져올 수 있습니다.

Parameter

token: API 토큰

Response

list[]: 노드 객체 배열
node_id: 노드 아이디
node_type: IoT.own 등록시 사용자가 임의 입력하는 정보
node_desc: IoT.own 등록시 사용자가 임의 입력하는 정보
created_at: IoT.own에 등록된 시간(UTC)
connected_gw_id (optional): 노드가 연결된 게이트웨이 아이디. 부팅 메세지가 누락된 경우 제외
bootup_time (optional): 마지막으로 부팅된 시간(UTC). 부팅 메세지가 누락된 경우 제외
last_data (optional): 마지막에 기록된 데이터 객체. 데이터가 한번도 기록되지 않은 경우 제외
last_timestamp (optional): 마지막 데이터가 기록된 시간(UTC). 데이터가 한번도 기록되지 않은 경우 제외

Example

https://town.coxlab.kr/api/node/get-list?token=00112233445566778899aabbccddeeff00112233445566778899aabbccddeeff

{
  "list" : [
    {
      "node_id":"N003",
      "node_type":"N003종류",
      "node_desc":"N003설명",
      "created_at":"2016-05-27T08:13:31.633Z"
    },
    {
      "node_id":"N002",
      "node_type":"N002종류",
      "node_desc":"N002설령",
      "bootup_time":"2016-05-26T08:07:05.893Z",
      "connected_gw_id":"GW001",
      "created_at":"2016-05-27T08:13:31.633Z",
      "last_data":{"CC":"33","BB":"11","AA":"00"},
      "last_timestamp":"2016-05-30T07:50:10.848Z"
    },
    {
      "node_id":"N001",
      "node_type":"N001종류",
      "node_desc":"N001설명",
      "created_at":"2016-05-27T08:13:31.633Z",
      "last_data":{
        "A":"0",
        "B":"1"
      },
      "last_timestamp":"2016-05-30T07:50:52.033Z"
    }
  ],
  "errorCode":0,
  "errorStr":""
}

4-5. GET node/get-info

URL: https://town.coxlab.kr/api/node/get-info

이 API를 통해서 IoT.own에 등록된 노드 정보를 가져올 수 있습니다.

Parameters

token: API 토큰
node_id: 노드 아이디

Response

node: 노드 객체
node_id: 노드 아이디
node_type: IoT.own 등록시 사용자가 임의 입력하는 정보
node_desc: IoT.own 등록시 사용자가 임의 입력하는 정보
created_at: IoT.own에 등록된 시간(UTC)
connected_gw_id (optional): 노드가 연결된 게이트웨이 아이디. 부팅 메세지가 누락된 경우 제외
bootup_time (optional): 마지막으로 부팅된 시간(UTC). 부팅 메세지가 누락된 경우 제외
last_data (optional): 마지막에 기록된 데이터 객체. 데이터가 한번도 기록되지 않은 경우 제외
last_timestamp (optional): 마지막 데이터가 기록된 시간(UTC). 데이터가 한번도 기록되지 않은 경우 제외

Example

https://town.coxlab.kr/api/node/get-list?token=00112233445566778899aabbccddeeff00112233445566778899aabbccddeeff&node_id=N001

{
  "node": {
    "node_id":"N001",
    "node_type":"N001종류",
    "node_desc":"N001설명",
    "created_at":"2016-05-27T08:13:31.633Z",
    "last_data":{
      "A":"0",
      "B":"1"
    },
    "last_timestamp":"2016-05-30T07:50:52.033Z"
  },
  "errorCode":0,
  "errorStr":""
}

4-6. GET storage/get-data

URL: https://town.coxlab.kr/api/storage/get-data

이 API를 통해서 IoT.own에 저장된 데이터를 가져올 수 있습니다.

Parameters

token: API 토큰
node_id (optional): 노드 아이디. 콤마(,)로 구분. (예 : node_id=N001,N002,N003) node_id가 없을 경우 모든 노드를 대상으로 검색
from (optional): 검색할 시간 범위의 시작값 UTC형태만 가능. (예: from=2016-06-01T13:45+09:00)
to (optional): 검색할 시간 범위의 끝값. UTC형태만 가능. (예: to=2016-06-25T13:45+09:00)
lastKey (optional): 검색 결과가 5000개를 초과할 경우, 5000개와 함께 lastKey가 리턴됨. 동일 검색 조건에 lastKey를 추가하여 다시 호출하면 다음 5000개를 리턴함.(반복적으로 5000개씩 로딩 가능)

Response

data: 검색된 데이터 객체 배열
node_id: 노드 아이디
name: 데이터 이름
value: 데이터 값
timestamp: 데이터가 기록된 시간(UTC)
lastKey (optional): 검색 결과가 5000개를 초과할 경우, 5000개와 함께 lastKey가 리턴됨. 동일 검색 조건에 lastKey를 추가하여 다시 호출하면 다음 5000개를 리턴함.(반복적으로 5000개씩 로딩 가능)

Example

주의사항 : UTC 사용시(from, to) + 기호 대신에 %2B를 사용해야 함.
( 예: 2016-02-30T01:25+09:00 -> 2106-02-30T01:25%2B09:00 )

https://town.coxlab.kr/api/storage/get-data?token=00112233445566778899aabbccddeeff00112233445566778899aabbccddeeff&node_id=N001,N002&from=2016-02-30T01:25%2B09:00&to=2016-12-01T01:01:20%2B09:00

{
  "data":[
  {
    "node_id":"N001",
    "name":"B",
    "value":"1",
    "timestamp":"2016-02-30T07:50:52.033Z"
  },
  {
    "node_id":"N001",
    "name":"A",
    "value":"0",
    "timestamp":"2016-02-30T07:50:52.033Z"
  },
  ...
  {
    "node_id":"N001",
    "name":"B",
    "value":"1",
    "timestamp":"2016-05-30T09:50:21.748Z"
  },
  {
    "node_id":"N001",
    "name":"A",
    "value":"0",
    "timestamp":"2016-05-30T09:50:21.748Z"
  },
  {
    "node_id":"N001",
    "name":"B",
    "value":"1",
    "timestamp":"2016-05-30T09:50:21.169Z"
  }
  ],
  "lastKey":"574bf0dbabe178ec1f776758",
  "errorCode":0,
  "errorStr":""
}

위의 예제처럼 lastKey가 리턴된 경우, 아래와 같이 다시 호출하면 다음 5000개를 불러옴.

https://town.coxlab.kr/api/storage/get-data?token=00112233445566778899aabbccddeeff00112233445566778899aabbccddeeff&node_id=N001,N002&from=2016-05-30T16:25%2B09:00&to=2016-12-01T01:01:20%2B09:00&lastKey=574bf0dbabe178ec1f776758

4-7. GET set-callback

URL: https://town.coxlab.kr/api/set-callback

이 API를 통해서 IoT.own으로 데이터가 들어올 때마다 특정 URL로 POST 하도록 설정할 수 있습니다. 자세한 내용은 How to use callback을 참고하시기 바랍니다.

Parameters

token: API 토큰
url: callback URL

Response

errorCode: 에러 코드
errorStr: 에러 코드 설명

Example

https://town.coxlab.kr/api/set-callback?token=00112233445566778899aabbccddeeff00112233445566778899aabbccddeeff&url=http://your.server.url

{
  "errorCode":0,
  "errorStr":""
}

4-8. GET get-callback

URL: https://town.coxlab.kr/api/get-callback

이 API를 통해서 set-callback으로 지정한 콜백 URL을 확인할 수 있습니다.

Parameter

token: API 토큰

Response

callbackURL: 등록된 URL
callbackStatus: URL의 상태 코드
- 0: 등록된 URL이 없음
- 1: 등록된 URL이 있음
- -1: URL 접속이 실패하여 콜백호출이 실패함 (예 : Connection timeout error)
- -2: URL 리턴값이 비정상인 이유로 콜백호출이 실패함 (예 : 404 에러)
errorCode: 에러 코드
errorStr: 에러 코드 설명

Example

https://town.coxlab.kr/api/get-callback?token=00112233445566778899aabbccddeeff00112233445566778899aabbccddeeff

{
  "callbackURL":"http://your.server.url",
  "callbackStatus":"1",
  "errorCode":0,
  "errorStr":""
}

4-9. GET clear-callback

URL: https://town.coxlab.kr/api/clear-callback

이 API를 통해서 set-callback으로 지정한 콜백 URL을 취소할 수 있습니다.

Parameter

token: API 토큰

Response

errorCode: 에러 코드
errorStr: 에러 코드 설명

Example

https://town.coxlab.kr/api/clear-callback?token=00112233445566778899aabbccddeeff00112233445566778899aabbccddeeff

{
  "errorCode":0,
  "errorStr":""
}

4-10. POST command

URL: https://town.coxlab.kr/api/command

이 API를 통해서 HTTP를 지원하는 IoT 장치로 명령을 전송할 수 있습니다.

Parameters

token: API 토큰
node_id: 노드 아이디
type: 커맨드 타입 ("hex" or "string")
command: 커맨드 내용

Response

errorCode: 에러 코드
errorStr: 에러 코드 설명

Example

type이 "string"인 경우,

{
  "token":"00112233445566778899aabbccddeeff00112233445566778899aabbccddeeff",
  "node_id":"LW1111222233334444",
  "type":"string",
  "command":"command_string_here"
}

type이 "hex"인 경우,

{
  "token":"00112233445566778899aabbccddeeff00112233445566778899aabbccddeeff",
  "node_id":"LW1111222233334444",
  "type":"hex",
  "command":"FF1234"
}

4-11. POST data

URL: https://town.coxlab.kr/api/data

이 API를 통해서 HTTP를 지원하는 IoT 장치에서 IoT.own으로 데이터를 전송할 수 있습니다.

Parameters

type: 메시지 형식 (문자열 “2”로 고정)
token: API 토큰
nid: 노드 아이디
data: 전송할 데이터 내용 (JSON object)

Response

errorCode: 에러 코드
errorStr: 에러 코드 설명

Example

{
  "type":"2",
  "token":"00112233445566778899aabbccddeeff00112233445566778899aabbccddeeff",
  "nid":"N0001",
  "data": {
    "temperature":26.1,
    "humidity":43
  }
}

OpenAPI Version : 1.0 (latest) Legacy (deprecated)

1. Introduction

2. API List

3. Error Descriptions

4. API Descriptions

4-1. GET gateway/get-list

Parameter

Response

Example

4-2. GET gateway/get-info

Parameters

Response

Example

4-3. GET gateway/connected-node-list

Parameters

Response

Example

4-4. GET node/get-list

Parameter

Response

Example

4-5. GET node/get-info

Parameters

Response

Example

4-6. GET storage/get-data

Parameters

Response

Example

4-7. GET set-callback

Parameters

Response

Example

4-8. GET get-callback

Parameter

Response

Example

4-9. GET clear-callback

Parameter

Response

Example

4-10. POST command

Parameters

Response

Example

4-11. POST data

Parameters

Response

Example

OpenAPI Version :