GATEWAY V2.2 모바일 API 연동규격서¶

사 용 권 한

본 문서에 대한 서명은 ㈜유라클 내부에서 본 문서에 대하여 수행 및 유지관리의 책임이 있음을 인정하는 것임.

제.개정 이력

버전	변경일자	제.개정 내용	작성자
1.0	2011.11.10	최초작성	이형기
2.0	2012.11.1	버전 2.0 개발 연동 가이드	이형기
2.1	2013.11.19	3.1. 리소스 업데이트 API 변경 (노랑색 부분 참조) - 업무별 리소스 배포기능 추가	유병희
2.2	2015.04.29	AES256 리소스 암호화 및 앱위변조방지 기능 API추가	유병희/나현조

Morpheus Mobile Server 연동을 위한 개요
1. 목적

본 문서는 Morpheus Mobile Client 와 Gateway Server간의 개발 연동을 위한 제반 사항을 기술한다.

고려사항¶

매뉴얼 변경 시에는 근거를 명시하고 버전 관리를 정확하게 수행한다.
데이터는 JSON 형식을 따르며 통신은 HTTP를 지원한다.
전문 내용 중 데이터 길이가 명시되지 않은 항목은 가변길이 이다.
Spring 프레임워크 3 버전 이상부터 RESTful 웹서비스 구현이 지원된다.
메시지 포맷 정의시 필수 사항은 M(Mandatory), 선택사항은 O(Optional)로 표시한다.
1. 참고
본 문서는 성능개선, 기능추가 등의 사항으로 내용이 변경 될 수 있다.

RESTful API 사용 정의¶

본 절에서는 Spring 3 버전 부터 제공 되는 RESTful 웹서비스를 구현을 위한 활용 방법 및 가이드에 대해 설명한다.

URI (Resource)¶

전체 시스템에서 유일한 식별 값을 갖는 주소를 정의한다. URI(Uniform Resource Identifiers)를 사용하여 주어진 자원 표현의 위치를 알아내고 접근 한다.

구분	설명	예제
직관적 단어	URI는 간단하고 직관적인 단어 사용(복수형 명사 또는 구체적인 이름)	/users/{userid}
계층적 표현	계층적으로 표현하고 상위 경로는 하위 경로의 집합의 의미하는 단어 사용	/owners/{ownerid}/pets/{petid}
Query String	자원간의 관계, 매개, 변수 및 속성 같은 리소스와 직접 관련 없는 정보는 HTTP Query String 으로 표현	/users/{userid}?age=20

HTTP Request Method¶

클라이언트는 URI를 이용하여 Resource를 지정하고 해당 Resource를 조작하기 위해서 Method를 사용한다. HTTP에서는 GET, POST, PUT, DELETE Method를 제공한다.

구분	설명	CRUD Operation
GET	리소스의 현재 상태 정보를 가져온다.	Read
POST	종속적인 리소스를 생성한다.	Create
PUT	현재 리소스를 변경한다.	Update
DELETE	리소스를 삭제한다.	Delete

HTTP Request Parameters¶

해당 서비스 리소스에 대한 추가적인 요청 정보에 대해서 Parameter (HTTP Query String)로 정의하여 사용하도록 한다.

구분	항목	Type	필수	설명
body	HTTP Method에 따른 선택적 정의 부분	String	O	해당 URI에 따른 값을 추가. (예: {“body”:{“deploy”:”0”…}})

HTTP Response¶

Mobile 서버에서 클라이언트로 전송된 메시지 포맷

구분	항목	Type	필수	설명
head	result_code	String	M	처리 응답 결과 코드
	result_msg	String	O	처리 응답 결과 메시지
body	사용자 정의 부분	String	M	해당 리소스에 대한 정보를 표현하고 값이 존재 하지 않으면 공란으로 채운다. (예: {“body”:””})

예제

{“head”:{“result_code”:”200”, “result_msg”:”OK”}, “body”:{“name”:”홍길동”}}

메시지 정의¶

클라이언트와 서버간 오류 메시지는 다음과 같이 정의한다.

코드구분	구분명	코드	설명
2xx	Successful	200	정상적으로 처리 되었습니다.
		204	클라이언트 요구를 처리했으나 전송할 데이터가 없습니다.
4xx	Client Error	400	클라이언트의 잘못된 요청으로 처리할 수 없습니다.
		401	클라이이언트 인증에 실패 하였습니다.
		405	리소스를 허용할 수 없습니다.
5xx	Server Error	500	서버에서 오류가 발생 하였습니다.
		502	서버가 과부하 상태 입니다.
		503	서버가 일시적으로 다운 되었습니다.
		504	장시간 미사용으로 서버접속이 종료 되었습니다.
		599	보안 프로그램 오류 입니다.
		598	보안 통신이 원활하지 않습니다.
		597	응답결과 데이터가 존재하지 않습니다.
		596	응답 데이터 형식 오류가 발생하였습니다.

RESTful API 설명¶

Morpheus 에서 제공되는 기본 API는 다음과 같다.

리소스명	Method	설명
리소스 업데이트	POST	리소스 파일 버전을 확인하여 최신 리소스 파일 정보를 가져온다.
DUMMY	GET	관리자로부터 입력된 Dummy 데이터를 가져온다.

리소스 업데이트 API¶

요청된 클라이언트의 리소스 파일 버전을 확인하여 최신 리소스 파일 정보를 가져온다.

3.1.1 Request

HTTP Request URL	비고
주소}:{Port}/{Context}/api/res/auto-update

HTTP Request Method	비고
POST

HTTP Request Headers
헤더명	헤더값	비고
Accept	application/json
Content-Type	application/x-www-form-urlencoded; charset=UTF-8

HTTP Request Parameters
Parameter	Type	필수	설명
access_key	String	O	모바일 서버에서 발급된 해당 API에 대한 권한 키

HTTP Request Body (JSON Format)
JSON Key	Type	필수	설명
head	appid	String	M	발급된 해당 앱 아이디
body	deploy	String	M	배포유형 (1, 0) 0 = 개발 1 = 운영
	update_check_files (배열)	role_id	String	M	업무아이디
		version	String	M	클라이언트의 현재 버전 번호 (000001 ~ 999999)
	rsp	String	M	라이선스 정보
	loginInfo	String	M	로그인 정보

예제)

{

“head”:{“appid “:””}

“body”:{

“deploy”:””,

“update_check_files”:[

{“role_id”:””,”version”:””},

{“role_id”:””,”version”:””}

]

“rsp”:””

}

3.1.2 Response

HTTP Response Body (JSON Format)
JSON Key	Type	필수	설명
head	result_code	String	M	처리 응답 결과 코드
	result_msg	String	O	처리 응답 결과 메시지
body	update_files (배열)	role_id	String	M	업무아이디
		role_name	String	M	업무이름
		files (배열)	url	String	M	라이선스 정보
			md5	String	M	다운로드 배포 파일의 MD5 문자열
		total_file_size	String	M	버전별 배포 파일의 전체 크기
		remove_files (배열)	String	M	삭제된 리소스 파일명 예: www/html/sample.html (res 폴더 하위 폴더부터 시작)
		version	String	M	배포유형 (1, 0) 0 = 개발 1 = 운영
	app_version_info	download_market_url	String	M	앱 다운로드 주소
		required_app_version	String	M	필수 앱 버전
		current_app_version	String	M	현재 앱 버전
	notice	title	String	M	공지사항 제목
		contents	String	M	공지사항 내용
	loginInfo	status			클라이언트에 해당정보 리턴
		userInfo

예제)

{

“head”:{

“result_code”:””,

“result_msg”:””

}

“body”:{

“update_files”:[

{“role_id”:””,”role_nm”:””,files”:[{“url”:””,”md5”:””}],”total_file_size”:””,”remove_files”:[],”version”:””},

],

“app_version_info”:{“download_market_url”:””,”required_app_verion”,”current_app_version”:””}

“notice”:{“title”:””,”contents”:””},

loginInfo:{status:{message:정상, state:0}, userInfo:{}}

}

앱 위변조 인증토큰 요청¶

요청된 클라이언트의 리소스 파일 버전을 확인하여 최신 리소스 파일 정보를 가져온다.

3.1.1 Request

HTTP Request URL	비고
주소}:{Port}/{Context}/getPreventToken

HTTP Request Method	비고
POST

HTTP Request Headers
헤더명	헤더값	비고
Accept	application/json
Content-Type	application/x-www-form-urlencoded; charset=UTF-8

HTTP Request Parameters
Parameter	Type	필수	설명

HTTP Request Body (JSON Format)
JSON Key	Type	필수	설명
head	screen_id
	system_name
	phone_no
	device_id
	app_version
	appid
body

3.1.2 Response

HTTP Response Body (JSON Format)
JSON Key	Type	필수	설명
head	result_code	String	M	처리 응답 결과 코드
	result_msg	String	O	처리 응답 결과 메시지
body	token	String	M	토큰키

예제)

{

“head”: {

“screen_id”: “0”,

“system_name”: “Android”,

“phone_no”: “1234567890”,

“app_version”: “0”,

“appid”: “kr.co.morpheus.mobile1”,

“device_md”: “SM-N900S”,

“device_id”: “257630051275603”,

“app_name”: “Morpheus”,

“callback_request_data_flag”: “n”,

“system_version”: “19”,

“user_id”: “user”,

“user_name”: “name”

},

“body”: {

“token”: “55be7083538e9fb72314f15c991b458287a6c228”

}

앱 위변조 체크¶

요청된 클라이언트의 리소스 파일 버전을 확인하여 최신 리소스 파일 정보를 가져온다.

3.1.1 Request

HTTP Request URL	비고
주소}:{Port}/{Context}/checkAppVerify

HTTP Request Method	비고
POST

HTTP Request Headers
헤더명	헤더값	비고
Accept	application/json
Content-Type	application/x-www-form-urlencoded; charset=UTF-8

HTTP Request Parameters
Parameter	Type	필수	설명

HTTP Request Body (JSON Format)
JSON Key	Type	필수	설명
head	screen_id
	system_name
	phone_no
	device_id
	app_version
	appid
	system_version
body	appID	String	M
	appVer	String	M
	osType	String	M	A:안드로이드, I:IOS
	hash_key	String	M
	token	String	M

예제)

3.1.2 Response

HTTP Response Body (JSON Format)
JSON Key	Type	필수	설명
head	result_code	String	M	처리 응답 결과 코드
	result_msg	String	O	처리 응답 결과 메시지
body	resources	hash	String
		name	String
		entry	String
		mtime	long
		size	int
	bundles	hash	String
		name	String
		entry	String
		mtime	long
		size	int
	build		string		앱위변조 빌드버전

예제)

{

“head”: {

“screen_id”: “0”,

“system_name”: “Android”,

“phone_no”: “1234567890”,

“app_version”: “0”,

“appid”: “kr.co.morpheus.mobile1”,

“device_md”: “SM-N900S”,

“device_id”: “257630051275603”,

“app_name”: “Morpheus”,

“callback_request_data_flag”: “n”,

“system_version”: “19”,

“user_id”: “user”,

“user_name”: “name”

},

“body”: {

“resources”: [

{

“hash”: “8e253d8a1f4946547058b7d90036023f”,

“name”: “Manifest.xml”,

“entry”: “assets\res\Manifest.xml”,

“mtime”: 1430282643288,

“size”: 2739

},

{

“hash”: “136257a30836c944537bd21868b6b52c”,

“name”: “lang.js”,

“entry”: “assets\res\locales\en-us\lang.js”,

“mtime”: 1430282643289,

“size”: 122

},

{

“hash”: “81e43ec82a8141d77715dfda4f07b0fa”,

“name”: “lang.js”,

“entry”: “assets\res\locales\ko-kr\lang.js”,

“mtime”: 1430282643290,

“size”: 122

},

“bundles”: [

{

“hash”: “8e253d8a1f4946547058b7d90036023f”,

“name”: “Manifest.xml”,

“entry”: “assets\res\Manifest.xml”,

“mtime”: 1430282643288,

“size”: 2739

},

{

“hash”: “136257a30836c944537bd21868b6b52c”,

“name”: “lang.js”,

“entry”: “assets\res\locales\en-us\lang.js”,

“mtime”: 1430282643289,

“size”: 122

}

],

build”: “1.0.0”

}

Dummy API¶

관리자로부터 입력된 Dummy 데이터를 가져온다.

3.1.1 Request

Request URL

비고

주소}:{Port}/{Context}/rest/api/dummy/{app_id}/{service_id}

app_id = 앱 아이디

service_id = 서비스 아이디(어드민에서 등록된 전문코드)

Request Method	비고
GET

Request Headers
헤더명	헤더값	비고
Accept	application/json
Content-Type	application/x-www-form-urlencoded; charset=UTF-8

HTTP Request Parameters
Parameter	Type	필수	설명
access_key	String	O	모바일 서버에서 발급된 해당 API에 대한 권한 키

3.1.2 Response

HTTP Response Body (JSON Format)

사용자 정의 영역