개발 가이드 > API 개요

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에 대한 추가적인 설명을 나타낸다.