IoTMakers는 IoTMakers 플랫폼에 저장된 다양한 정보(디바이스, 태그스트림, 이벤트, 공개디바이스)를 활용할 수 있는 IoT 서비스 애플리케이션 개발을 위해 두 가지 방식을 지원합니다.
애플리케이션 개발을 위한 IoTMakers 플랫폼의 주요 지원 기능
정의 (Open API)
Open API 사례
Open API의 장단점
Open API 범주
SOAP 및 REST는 웹 서비스를 호출하는 다양한 방법을 제공합니다. SOAP 기반 API는 일반적으로 XML을 데이터 교환 형식 으로 사용 하지만 RESTful API는 일반적으로 JSON을 마샬링 합니다.
REST API에 대해 좀더 구체적으로 공부해 보겠습니다.
사전 지식
발표 당시의 웹이 HTTP의 설계 상 우수성을 제대로 사용하지 못하고 있는 상황을 보고 웹의 장점을 최대한 활용할 수 있는 아키텍쳐로서 REST를 소개하였고 이는 HTTP 프로토콜을 의도에 맞게 디자인하도록 유도하고 있다. REST의 기본 원칙을 성실히 지킨 서비스 디자인을 “RESTful”이라고 표현한다.
REST 아키텍처 스타일
Client-Server Style
Client-Stateless-Server (CSS) Style
캐시
균일한 인터페이스
Layered System
시스템에 대한 지식을 단일 계층으로 제한함으로써 전체 시스템 복잡성을 제한하고 계층의 독립성을 촉진시키지만, 주요 단점은 데이터 처리에 오버 헤드와 대기 시간을 추가하여 사용자가인지하는 성능을 저하 시킨다는 점입니다.
REST Server는 다중 계층으로 구성될 수 있다.
API Server는 순수 비즈니스 로직을 수행하고 그 앞단에 보안, 로드밸런싱, 암호화, 사용자 인증 등을 추가하여 구조상의 유연성을 줄 수 있다[2]
REST API는 웹 상의 어떤 자원에 대한 처리를 위해서 다음 3가지 구성요소로 정의한 API
예를 들어서 이름이 Terry인 사용자를 생성한다
라는 호출이 있을 때, 사용자
는 생성되는 리소스 , 생성한다
라는 행위는 메서드 그리고 이름이 Terry인 사용자
는 자원의 표현이 된다. 이를 REST 형태로 표현해보면 아래와 같다.
POST http://myweb/users/
{
"users":{
"name":"terry"
}
}출처: https://bcho.tistory.com/953 [조대협의 블로그]
URI는 정보의 자원을 표현해야 한다.
자원에 대한 행위는 HTTP Method(GET, PUT, POST, DELETE 등)로 표현한다
id가 1인 member를 생성
POST /members/
{
"id":"1"
}id가 1인 member를 조회
GET /members/1id가 1인 사용자의 이름을 bob
으로 수정
PUT /members/1
{
"id":"1",
"name":"bob"
}id가 1인 member를 삭제
DELETE /members/1JSON에 대한 자세한 튜토리얼은 http://tcpschool.com/json/intro 를 참조하고, 핵심적인 내용만 간단히 설명합니다.
JSON 문법
JSON 객체는 중괄호({})로 둘러 쌓아 표현합니다.
JSON에서 사용할 수 있는 값은 다음과 같은 타입이 올수 있습니다.
JSON 예제
객체
{
"name": "식빵",
"family": "웰시코기",
"age": 1,
"weight": 2.14
}객체 안의 객체
{
"dog": {
"name": "식빵",
"family": "웰시코기",
"age": 1,
"weight": 2.14,
"owner": {
"ownerName": "홍길동",
"phone": "01012345678"
}
}
}배열
{
"dog": [
"웰시코기",
"포메라니안",
"푸들"
]
}{
"dog": [
"웰시코기",
"포메라니안",
"푸들",
{
"ownerName": "홍길동",
"phone": "01012345678"
}
]
}APP 이나 Web 에서 사용 가능한 Open API 목록: http://iotmakers.kt.com/openp/index.html#/openapi
검색한 API에 요청변수 값을 넣어 테스트 해볼 수 있습니다.
디바이스 모델 수정
디비이스 모델의 모델명
을 수정하기 위해서 다음과 같이 요청변수를 설정합니다.
[디바이스 모델 일련변호]: 디바이스 모델 목록 조회 결과에서 sequence 속성 값을 설정
[변경할 속성을 정의한 JSON 문자열]:
{
"name" : "raspberry pi device"
}[API 테스트] 버튼을 클릭하여 응답결과를 확인해 본다.
디바이스 모델 등록
요청변수 형식
{
"id" (string, mandatory): "모델 아이디",
"name" (string, mandatory): "모델 명",
"type" (string, mandatory): "모델 유형",
"protocolType" (string, mandatory): "프로토콜 구분",
"bindingType" (string, mandatory): "프로토콜 유형",
}요청변수 예제
{
"id": "my_device_model_id_001",
"name": "my device model",
"type": "0044",
"protocolType": "0004",
"bindingType": "0001"
} [API 테스트] 버튼을 클릭하여 응답결과를 확인해 본다.
디바이스 등록
요청변수 형식
{
"id" (string, mandatory): "디바이스 아이디",
"name" (string, mandatory): "디바이스 명",
"description" (string, optional): "디바이스 상세정보",
"used" (boolean, optional): 디바이스 사용여부,
"published" (boolean, optional): 디바이스 공개여부,
"status" (string, optional): "디바이스 상태",
"firmwareVersion" (string, optional): "디바이스 펌웨어 버전",
"authenticationId" (string, optional): "디바이스 인증 ID",
"authenticationKey" (string, mandatory): "디바이스 인증 키",
"connectionId" (string, mandatory): "디바이스 연결 ID",
"connectionType" (string, optional): "디바이스 연결 유형",
"creator" (string, mandatory): "디바이스 생성자 일련번호",
"model" (model object, mandatory): {
"sequence": 모델 일련번호
}
}요청변수 예제
{
"id" : "kwleemyid_001",
"name" : "my device",
"authenticationKey" : "kwlee_authenticationKey",
"connectionId" : "kwlee_connectionID001",
"creator" : "kwlee",
"model" : {
"sequence": 2000009822
}
}[API 테스트] 버튼을 클릭하여 응답결과를 확인해 본다.
디바이스 모델/디바이스 상세 조회
디바이스 모델/디바이스 삭제
태그스트림 목록 상세조회
태그스트림 로그 조회 (요청시간 단위)
이벤트 목록 조회
이벤트 발생 로그 (이벤트 ID)
IoTMakers에서는 다음과 같은 기본 표준체계를 사용하고 있으므로 원활한 개발을 위하여 API규격에 대한 숙지를 하시기 바랍니다.
HTTP 메소드
(PUT, DELETE 메소드 미지원 브라우저는 사용이 제한적임)
URL구조 (RESTful 방식)
http(s)://iotmakers.kt.com:443/api/{version}/{Resource Category}/{Resource}/{Path Variable}/…?{Query String}리턴형식
리턴 값 구조 예제
{
"responseCode": "200",
"paging": {
"total": 5,
"offset": 1,
"limit": 10
},
"data": [
{
"sequence": 2000009551,
"id": "mbr_1000003350_kwanu7D1568547817662",
"name": "kwanu70My Sample Device",
"type": "0044",
"protocolType": "0004",
"bindingType": "0001",
"creator": "1000003350",
"createdOn": 1568547838683,
"sensingTags": [
{
"sequence": 1000029860,
"code": "LED",
"name": "LED",
"type": "0000020",
"dataType": "STRING",
"individual": true
},
{
"sequence": 1000029861,
"code": "temperature",
"name": "temperature",
"type": "0000010",
"dataType": "DOUBLE",
"individual": true
}
]
},
{
"sequence": 2000009579,
"id": "mbr_1000003350_kwanu7D1568790871581",
"name": "kwanu70android device",
"type": "0044",
"protocolType": "0004",
"bindingType": "0001",
"creator": "1000003350",
"createdOn": 1568790948107,
"sensingTags": [
{
"sequence": 1000029923,
"code": "latitude",
"name": "latitude",
"type": "0000010",
"dataType": "DOUBLE",
"individual": true
},
{
"sequence": 1000029924,
"code": "longitude",
"name": "longitude",
"type": "0000010",
"dataType": "DOUBLE",
"individual": true
}
]
},
{
"sequence": 2000009822,
"id": "my_device_model_id_001",
"name": "my device model",
"type": "0044",
"protocolType": "0004",
"bindingType": "0001",
"creator": "1000003350",
"createdOn": 1570335699596
}
]
}등록 절차
포탈 메뉴 상단의 IoT 개발 탭 내 앱 등록 메뉴에서 아래와 같이 [App 등록] 버튼을 클릭하여 앱을 등록 합니다.
기본정보 입력
상세정보 입력
index.html: 시작 html 페이지
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>IoTMakers Open API Sample</title>
<!-- JQuery 라이브러리 설정 -->
<script src="https://code.jquery.com/jquery-3.4.1.min.js" integrity="sha256-CSXorXvZcTkaix6Yvo6HppcZGetbYMGWSFlBw8HfCJo=" crossorigin="anonymous"></script>
<!-- 디바이스 조회 자바스크립트 로딩-->
<script src="list_devices.js"></script>
</head>
<body>
<h3>IoTMakers Open API Sample</h3>
<h4>나의 디바이스 목록</h4>
<div>조회된 데이터가 없습니다</div>
<ul> </ul>
</body>
</html>list_device.js: JQuery 기반 Javascript 코드
var token; // access token을 저장하기 위한 변수
var requestTokenAwareApi = function(callback, args){
var appId = "APP_ID_HERE"; // 변경해야 함
var secret = "SECRET_HERE"; // 변경해야 함
var uName = "USERNAME_HERE"; // 변경해야 함
var pw = "PASSWORD_HERE"; // 변경해야 함
//App ID, Secret, 계정아이디, 계정 비밀번호를 기반으로 access token 획득
$.ajax('https://iotmakers.kt.com/oauth/token', {
method: 'POST',
xhrFields: { withCredentials: false },
headers: { 'Authorization': 'Basic ' + btoa(appId + ':' + secret)},
data: { grant_type: 'password',
username: uName,
password: pw
},
success: function(result) {
token = result.access_token; // 성공시, access token 저장
},
error: function(xhr,status,error){
console.log(xhr);
}
});
};
requestTokenAwareApi(); // access token 획득위한 코드 수행
setTimeout(function() { // 0.3초 후에 invokeAPI() 수행
invokeAPI();
}, 300);
var invokeAPI = function() {
// 디바이스 조회 URI
var API_URI = '/api/v1.1/devices?offset=0&limit=10';
$.ajax('https://iotmakers.kt.com' + API_URI, {
method: 'GET',
headers: { 'Authorization': 'Bearer ' + token},
contentType: "application/json",
dataType:"json",
success: function (data, status, xhr) {
setDataList(data.data); // 성공시, 데이터 출력을 위한 함수 호출
},
error: function(xhr,status,e){
alert("error");
}
});
};
// 데이터 출력을 위한 함수
var setDataList = function(data){
data.forEach(function(v){
var li = document.createElement("li"); // <li> 태그 생성
li.innerText = v.name; // <li> 태그 내에 디바이스 이름 세팅
$("ul").append(li); // <ul> 태그안에 <li> 추가
})
if(data.length>0){
// 디바이스 목록 조회결과가 있는 경우 데이터가 없습니다 메시지 삭제
document.getElementsByTagName("div")[0].remove();
}
}
index.html: 시작 html 페이지 (수정)
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>IoTMakers Open API Sample</title>
<!-- JQuery 라이브러리 설정 -->
<script src="https://code.jquery.com/jquery-3.4.1.min.js" integrity="sha256-CSXorXvZcTkaix6Yvo6HppcZGetbYMGWSFlBw8HfCJo=" crossorigin="anonymous"></script>
<!-- 디바이스 조회 자바스크립트 로딩-->
<script src="list_devices2.js"></script>
</head>
<body>
<h3>IoTMakers Open API Sample</h3>
<h4>나의 디바이스 목록</h4>
<div>조회된 데이터가 없습니다</div>
<table >
<tr style="background-color:lightgrey">
<th>디바이스 명</th>
<th>디바이스 아이디</th>
</tr>
</table>
</body>
</html>list_device.js: JQuery 기반 Javascript 코드 (수정)
// 데이터 출력을 위한 함수
var setDataList = function(data){
data.forEach(function(v){
var tr = document.createElement("tr");
var td1 = document.createElement("td");
var td2 = document.createElement("td");
td1.innerText = v.name;
td2.innerText = v.id;
tr.appendChild(td1);
tr.appendChild(td2);
$("table").append(tr);
})
if(data.length>0){
// 디바이스 목록 조회결과가 있는 경우 데이터가 없습니다 메시지 삭제
document.getElementsByTagName("div")[0].remove();
}
}실행결과
REST, REST API, RESTful에 대해 이해한다, https://gmlwjd9405.github.io/2018/09/21/rest-and-restful.html
Representational State Transfer (REST), https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm
REST API 제대로 알고 사용하기, https://meetup.toast.com/posts/92