API (to be deleted)

교육 동영상 : https://drive.google.com/file/d/17t39s4P6icFlWFj-k5o6SZE4zLSGQ0vB/view?usp=sharing

ICE에서 API는 크게 자동 생성 API와 설정 API로 구분할 수 있다.

자동 생성 API

자동 생성 API는 내부 통신에서만 사용되는 API이며, 새로운 NodeType을 만들면 자동으로 생성되는 5개의 Event( Create,Update,Delete,Read,List)를 포함한 모든 이벤트에 대해서 직접 호출 할 수 있는 API이다.

API 호출 패턴

자동 생성 API는 http://{Domain}/{Api Type}/{NodeType}/{Event} 형태로 호출할 수 있다.

만약 Backoffice에서 content NodeType의 list 이벤트를 호출한다면 http://{Domain}/adm/content/list 와 같은 형태로 API를 호출 할 수 있다.

API 호출 Method

자동 생성 API는 해당 이벤트의 유형에 따라서 사용가능한 Method가 다음과 같이 제한된다.

Command형 이벤트 : Event의 noneExecute가 false인 이벤트(ex create, update, delete)는 POST 메소드만 호출 가능

Query형 이벤트 : read, list와 같이 noneExecute가 true인 이벤트는 GET과 POST 둘다 허용

인증

자동 생성 API는 내부에서만 사용해야하기 때문에 인증 토큰과 로그인 세션이 없는 호출은 모두 401에러를 발생한다.

설정 API

설정 API는 Platform Console의 API 설정 기능이나 스키마의 API 설정 Json 파일을 이용하여 정의한 API로 FrontOffice와 외부 인터페이스에 사용된다.

API 설정 정보의 구조는 다음과 같다.

API Category

API 카테고리는 API를 그룹화 하여 관리하기 위해서 사용하며, 하위 API에 대한 공통 설정을 정의할 수 있다. 예를들어, API 카테고리에 권한을 설정하면, 하위 API는 모두 같은 해당 권한을 일차적으로 체크하게 된다.

API Category는 다음과 같은 속성을 정의한다.

pid	valueType	description

pid	valueType	description
id	STRING	생성할 apiCategory의 ID이며 API 호출 URL의 2번째 Path에 사용
categoryName	STRING	apiCategory의 이름
apiType	CODE	API 유형
apiAuthority	REFERENCES	권한
dateFormat	STRING	dateFormat 설정(하위의 api에 공통으로 적용) `yyyy-MM-dd HH:mm:ss"`
fileUrlFormat	JSON	API에 리턴되는 file URL의 Prefix 설정(하위의 api에 공통으로 적용) { "default": "{{:getEnvValue('core.cluster.api-url-prefix')}}" }
commonParameters	CHILDREN	공통 Parameter 정의(하위의 api에 공통으로 적용)
commonResponse	CHILDREN	하위 API Config에서 사용할 기본 Response 정의

API Type

ICE의 API 유형은 다음과 같이 구분한다.

service
- 목적 : FrontOffice에서 사용하는 API
- Path : /svc/categoryID/apiID 와 같이 svc라는 path로 시작
- 인증 : siteId가 항상 포함되어 있으며, Customer의 세션을 사용한다.
admin :
- 목적 : Admin 사용자용 BackOffice를 위한 API
- Path : adm Path를 사용
- 인증 : 반드시 로그인된 Admin 사용자만 사용 가능
manager
- 목적 : Manger 사용자용 BackOffice를 위한 API
- Path : mng Path를 사용
- 인증 : 반드시 로그인된 Manager 사용자만 사용 가능
external
- 목적 : 외부 또는 레거시 시스템과 연동을 위해서 사용하는 API
- Path : ext
- 인증 : API 키를 통해서 인증
internal
- 목적 : ICE 내부 서비스간 연동을 위해서 사용하는 API
- Path : int
- 인증 : 클러스터에 등록된 서버들만 통신 가능
open
- 목적 : 오픈 API에 사용
- Path : api
- 인증 : API Key를 이용한 인증 사용, 요구사항에 따라서 인증 방식 확장이 가능(OAuth 등)

설정 예

  {
    "typeId": "apiCategory",
    "id": "product",
    "categoryName": "product API",
    "dateFormat": "yyyy-MM-dd HH:mm:ss",
    "fileUrlFormat": {
      "default": "{{:getEnvValue('core.cluster.api-url-prefix')}}"
    },
    "commonParameters": [
      {
        "parameter": "_siteId",
        "required": true
      },
      {
        "parameter": "_deviceType",
        "required": true
      }
    ],
    "commonResponse": [
      {
        "field": "time",
        "type": "field",
        "value": "{{:sysdate}}"
      }
    ]
  }

API

API 설정은 API 호출에 대한 형식을 정의하며, 실제 API의 동작은 apiConfig로 정의한다. 하나의 API는 여러개의 API Config를 설정함으로써 API GW의 Aggregation 기능을 제공한다.

pid	valueType	description

pid	valueType	description
category(*)	REFERENCE	상위 API 카테고리 지정
apiId(*)	STRING	API의 아이디이며 API URL의 마지막 path에 사용
apiName	STRING	API 명칭
method	CODE	API 호출 Method (POST, GET, PUT, DELETE, PATCH)
apiType	CODE	API 유형
apiAuthority	REFERENCES	권한
secure	BOOLEAN	SSL만 허용 여부
signed	BOOLEAN	로그인된 사용자만 허용 여부
parameters	CHILDREN	호출 파라미터 정의
config	CHILDREN	실제 API 동작 설정

API Parameter

API 파라미터 설정은 호출하는 파라미터를 제한하고 필수 파라미터를 정의한다.

pid	valueType	description

pid	valueType	description
id	INT	자동 생성 아이디
parameter	STRING	호출 파라미터
name	STRING	파라미터 명칭
required	BOOLEAN	필수 여부
valueType	CODE	파라미터 값 유형(String, Number, File, Object, Array)
description	TEXT	설명

API Config

apiConfig는 실제 API 동작을 정의하는데 사용하며, configId 에 따라서 API Response 형태가 결정된다.

pid	valueType	description

pid	valueType	description
id	INT	자동 생성 아이디
targetId	PARENT	상위 API
configId	STRING	동일 API에 여러개의 apiConfig가 설정되는 경우 API 응답 명칭을 의미, ROOT로 설정하는 경우 응답의 최상위에 해당 apiConfig 결과가 Merge
type	CODE	apiConfig의 유형 (query, event, select, relay, read, form… 등)
tid	REFERENCE	API 유형이 NodeType이 필요한 경우(query, event,read,reads,form) 대상 Node Type
resultType	CODE	응답 형태(array, object, none, page)
cacheable	BOOLEAN	캐시 사용 여부
cacheTime	INT	캐시 시간(초)
keepCache	BOOLEAN	캐시 유지 여부
excludeCacheKey	STRING	캐시키에서 제외할 파라미터 목록(예: timeStamp,userId)
allowParams	BOOLEAN	파라미터 쿼리에 대한 허용 여부
if	STRING	해당 apiConfig에 대한 실행 여부 테스트(EL 사용) {{:equals(siteId, ‘dxp’)}}
connectTimeout	INT	대상 서비스의 커넥션 타임아웃 설정 ms (default : 5000)
readTimeout	INT	대상 서비스의 응답 타임아웃 설정 ms (default : 10000)
customResponse	STRING	응답 결과에 대한 추가적인 처리가 필요한 경우 해당 서비스 정의
failOver	CODE	타임아웃이 발생하거나 500번대 에러가 발생하는 경우 이에 대한 처리 none : 에러 응답 리턴 retry : 재시도 last : 마지막 응답 결과 전송 compensating : 보상 API 호출
compensatingAPI	REFERENCE	failOver가 compensating일 경우 보상 API 지정
data	CHILDREN	해당 API Config를 호출하기 위한 파라미터를 재정의
response	CHILDREN	해당 API Config의 응답 필드에 대한 정의
orderNo	INT	API Config 실행 순서

Query Type

ICE 내부 특정 NodeType에 대한 쿼리를 실행하기 위한 API 유형으로, 다음과 같은 추가적인 항목을 정의한다.

pid	valueType	description

pid	valueType	description
tid	REFERENCE	대상 Node Type
customFilter	STRING	프로그래밍으로 검색 질의를 작성하고 싶은 경우 해당 필터 클래스 설정
query	CHILDREN	Query는 ICE내에서 공통으로 사용하는 Lucene 기반의 QUERY 을 이용하여 검색 조건을 정의

Event Type

ICE 내부 특정 NodeType에 정의된 Event를 실행하기 위한 API 유형으로, 다음과 같은 추가적인 항목을 정의한다.

pid	valueType	description

pid	valueType	description
tid	REFERENCE	대상 Node Type
event	REFERENCE	대상 노드타입의 실행하기 위한 Event 정의

Select Type

ICE에 Datasource가 정의된 DB에 대한 쿼리를 실행한다.

pid	valueType	description

pid	valueType	description
datasource	REFERENCE	대상 Datasource
sql	TEXT	실행할 SQL이며, EL을 활용하여 정의

sql의 경우 일반적으로 사용하는 EL과 SQL을 위한 EL 두가지를 사용 가능하다. SQL용 EL은 Prepared Statement 변환되기 때문에 문제 없지만, 일반 EL은 SQL Injection을 반드시 고려해야 한다.

select title from content where category = @{categoryId}
-> select title from content where category = ?
select title from {{:contentType}} where category = @{categoryId}
-> select title from movie where category = ?

Relay Type

외부 API를 중계하기 위한 유형이며, 대상 API응답이 XML인 경우는 JSON변환되어 리턴

pid	valueType	description

pid	valueType	description
relayUrl	STRING	중계 대상 URL을 정의하며, EL을 활용하여 동적으로 변경 가능
relayMethod	STRING	대상 API를 호출하는 Method 정의
data	CHILDREN	호출 파라미터를 정의하며, EL 활용 가능

Method Type

특정 클래스를 직접 실행하기 위한 유형, 지정된 Metho를 직접 실행

Process Type

Process Builder로 정의 프로세스 실행

API Response

ICE의 API Response는 result와 resultMessage를 항상 포함하고 있으며, 다른 필드는 API 설정에 따라서 변경된다.

    "result": "200",
    "resultMessage": "SUCCESS",

Result Code

ICE의 API 응답 코드는 기본적으로 HTTP의 응답 코드를 준용하여 사용한다.

Code	Description

Code	Description
200	성공
400	파라미터 오류
401	로그인 필요
403	권한 오류
404	Not Found
500	서버 에러

resultMessage는 해당 오류에 대한 메세지를 표시한다.

API 설정에서의 응답 항목은 다음과 같이 정의한다.

pid	valueType	description

pid	valueType	description
id	INT	자동 생성 ID
targetId	REFERENCE	해당 API 설정
field	STRING	응답 필드 명
type	CODE	응답 필드 유형 all : 전체 응답 필드를 바이패스 position : 목록형일 경우 해당 응답의 순서 field : fieldId와 동일한 응답 항목 매핑 mapping : value에 정의한 값으로 매핑 config : 하위에 다른 API 결과를 조합하여 응답을 생성
value	STRING	매핑 값, EL 사용 가능
config	CHILDREN	type이 config인 경우 하위 API Config 설정