1. System 개요
KBS N-Screen 연구사업 프로젝트의 서버 시스템이다. 서버는 클라이언트에게 RESTful 서비스를 제공함을 목적으로 하며, KBS N-Screen API 서비스라고 명명한다. KBS N-Screen API 서비스는 클라이언트와 데이터 교환을 그 목적으로 한다.
2. KBS N-Scree API 서비스 개요
KBS N-Screen API 서비스는 KBS N-Screen Client (이하 Client)와의 데이터 교환을 목적으로 하는 API (Application Programming Interface)를 정의한다. Client는 별도의 전문 구성 없이 HTTP GET/POST 방식을 지원하는 REST 방식에 따라 본 문서에서 정의한 KBS N-Screen API를 호출하고, RESTful 웹 서비스 표준 형태인 JSON 형태의 응답 데이터를 받아 처리한다.
2.1. JSON 메시지 예시
{
"objectType" : 2 ,
"name" : "마인드웨어" ,
"profilePicPath" : "/data/profile/userId/34/mww.jpg" ,
"prContent" : "마인드웨어 입니다" ,
"relationIndex" : 729 ,
"writingPermission : 1 ,
contactList: [{
"uID" : "sykim91" ,
"uName" : "김수용" ,
"thumbPicPath" : "/data/profile/userId/29/sykim.jpg",
"postingTime" : "2010.04.15 13:02:54",
"content" : "계정생성 축하합니다" ,
"thumbnailPath" : null,
"sourceId" : null,
"souceName" : null,
"replyCount" : 1,
"likeCount" : 1,
"hideYN" :"N"
},
{
"uID" : "squall" ,
"uName" : "이재" ,
"thumbPicPath" : "/data/profile/userId/31/squall.jpg",
"postingTime" : "2010.04.15 15:02:54",
"content" : "일등~" ,
"thumbnailPath" : null,
"sourceId" : null,
"souceName" : null,
"replyCount" : 3,
"likeCount" : 0,
"hideYN" :"N"
}
],
"position" : {
"latitude" : 37.21,
"longitude": 127.02
}
}
2.2. Sequence 예시
-
3. KBS N-Screen API 표기
3.1. 설명
3.1.1. 기본개요
[제공 배경] 항목은 API에 대한 추가적인 설명을 서술한다.
[암호화 처리 여부]는 https 사용 여부를 나타낸다. (기본 포트는 443)
오퍼레이션 명은 URL 에 나타나는 API 명을 나타낸다.
오퍼레이션 경로는 URL 경로를 나타낸다.
오퍼레이션 타입은 HTTP Method를 나타낸다.UMS의 OpenAPI에서는 GET/POST 방식의 Request를 지원한다.
3.1.2. Request 형식
GET : http://nscreen.kbs.co.kr/api/오퍼레이션경로/오퍼레이션명?Attribute-name=Attribute-value&Attribute-name2=Attribute-value2 방식으로 Request를 구성한다.
POST : http://nscreen.kbs.co.kr/api/오퍼레이션경로/오퍼레이션명 의 URL에 POST 방식의 Request Body를 구성하여 전송한다.
Request에 List 형식의 값을 넣어야 하는 경우에는 count 값과 함께 각 항목의 suffix로 "_순번" 을 붙인다. 문서에서의 표기는 "_%d" 이다. 순번은 0부터 시작하는 인덱스(zero-based Index) 이다.
3.1.3. Response 형식
JSON 형태이다.
JSON은 계층적인 데이터 구조의 표현이 가능함으로 따로 계층적인 데이터 구조에 대한 표기법을 가지지는 않고, JSON 표기 방식에 따른다.
3.1.4. Attribute-name
Request에서는 이름/값 쌍의 이름을 뜻한다.
Response에서는 JSON 객체의 Attribute 명을 뜻한다.
Response에서는 JSON 객체의 Attribute를 표기하는 방식에 따른다.
- 내장형 속성에 대해서는 객체.attribute 형식으로 표기한다.
-
객체가 내부 객체를 가지고 있고, 해당 내부객체의 속성이 있다면 외부객체.내부객체.내부객체 attribute 형식으로 표기한다.
-
JSON 객체는 기본적으로 해당 API의 Response에 명기 되지 않은 추가 속성을 가질 수 있고 실제 응답에 해당 속성들은 가비지 데이터를 가지고 나타날 수 있다. API 정의에서는 API를 통해 명확하게 제공되는 속성만 명시함을 원칙으로 한다. 클라이언트에서는 API에 명기된 속성만 접근함을 원칙으로 한다.
3.1.5. Attribute
Attribute가 뜻하는 내용을 나타낸다.
3.1.6. Type
문자형일 경우 최대 길이를 나타낸다.
문자형 이외의 경우 해당 Type명을 명기하고, 해당 Type의 제한에 따른다.
코드표에 따로 값을 명기한 경우 CODE라고 명기한다.
Response의 Type에서 JSON Array의 이름인 경우에는 ARRAY라고 명기한다.
Response의 Type에서 JSON Object의 이름인 경우 OBJECT 라고 명기한다.
3.1.7. ETC
Attribute에 대한 추가적인 설명을 나타낸다.
|