API 설정은 API 호출에 대한 형식을 정의하며, 실제 API의 동작은 apiConfig로 정의한다.
...
| Info |
|---|
{{protocol}}://{{hostname}}:{{port}}/{{apiType}}/{{apiCategory}}/{{api}} |
API는 다음과 같은 속성을 정의한다.
Event Type
ICE 내부 특정 NodeType에 정의된 Event를 실행하기 위한 API 유형으로, 다음과 같은 추가적인 항목을 정의한다.
...
pid
...
valueType
...
description
...
tid
...
REFERENCE
...
대상 Node Type
...
event
...
REFERENCE
...
대상 노드타입의 실행하기 위한 Event 정의
Select Type
ICE에 Datasource가 정의된 DB에 대한 쿼리를 실행한다.
...
pid
...
valueType
...
description
...
datasource
...
REFERENCE
...
대상 Datasource
...
sql
...
TEXT
...
실행할 SQL이며, EL을 활용하여 정의
sql의 경우 일반적으로 사용하는 EL과 SQL을 위한 EL 두가지를 사용 가능하다. SQL용 EL은 Prepared Statement 변환되기 때문에 문제 없지만, 일반 EL은 SQL Injection을 반드시 고려해야 한다.
| Code Block |
|---|
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
...
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 설정에 따라서 변경된다.
| Code Block |
|---|
"result": "200",
"resultMessage": "SUCCESS", |
Result Code
ICE의 API 응답 코드는 기본적으로 HTTP의 응답 코드를 준용하여 사용한다.
...
Code
...
Description
...
200
...
성공
...
400
...
파라미터 오류
...
401
...
로그인 필요
...
403
...
권한 오류
...
404
...
Not Found
...
500
...
서버 에러
resultMessage는 해당 오류에 대한 메세지를 표시한다.
...
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 | 로그인된 사용자만 허용 여부 |
parametersaggregation | CHILDREN | 호출 파라미터 정의 |
config | CHILDREN | 실제 API 동작 설정 |
API Parameter
API 파라미터 설정은 호출하는 파라미터를 제한하고 필수 파라미터를 정의한다.
...
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
...
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
...
tid
...
REFERENCE
...
대상 Node Type
...
customFilter
...
STRING
...
프로그래밍으로 검색 질의를 작성하고 싶은 경우 해당 필터 클래스 설정
...
query
...
CHILDREN
...
Query는 ICE내에서 공통으로 사용하는 Lucene 기반의 QUERY 을 이용하여 검색 조건을 정의
BOOLEAN | 하나 이상의 apiConfig를 이용하여 여러 API를 조합하여 실행할지를 결정 | |
statistic | BOOLEAN | 해당 API를 통계에 사용할지를 결정, false일 경우 API 로그에 7일만 보관되고 삭제 |
parameters | CHILDREN | 호출 파라미터 정의 |
root | PART | aggregation이 false인 경우 단독 apiConfig 설정 |
config | CHILDREN | aggregation이 true인 경우 다중 apiConfig 설정 |
method
API 호출 Method
POST, GET, PUT, DELETE, PATCH
| Code Block |
|---|
{
"typeId": "api",
"category": "product",
"apiId": "read",
"apiName": "상품 조회",
"apiType": "service",
"method": "GET"
} |
sample api
{{protocol}}://{{hostname}}:{{port}}/svc/product/read?
_siteId=bestshop
_deviceType=pc
productId=1323881205
→ POST
| Code Block |
|---|
{
"result": "405",
"resultMessage": "허용하지 않는 Method 입니다."
} |
→ GET
| Code Block |
|---|
{
"result": "200",
"resultMessage": "SUCCESS",
"item": {
"id": 1323881205,
"name": "[LG전자] X2 자급제폰(32GB)",
...
} |
apiType
|
|---|
apiAuthority
secure
SSL만 허용 여부
| Code Block |
|---|
{
"result": "500",
"resultMessage": "허용하지 않는 Protocol 입니다."
} |
signed
로그인된 사용자만 허용 여부
| Code Block |
|---|
{
"result": "401",
"resultMessage": "로그인이 필요합니다."
} |
aggregation
하나 이상의 apiConfig를 이용하여 여러 API를 조합하여 실행할지를 결정
false 이면 root 설정 필수
true 이면 config 설정 필수
root
aggregation이 false인 경우 단독 apiConfig 설정
| Code Block | ||
|---|---|---|
| ||
{
"typeId": "api",
"category": "product",
"apiId": "read",
"apiName": "상품 조회",
"apiType": "service",
"method": "GET",
"parameters": [
],
"aggregation": false,
"root": {
"configId": "root",
"tid": "siteProduct",
"type": "query",
"resultType": "OBJECT",
"query": [
{
"method": "matching",
"field": "id",
"value": "{{:productId}}"
}
],
"response": [
]
}
} |
config
aggregation이 true인 경우 다중 apiConfig 설정
| Code Block | ||
|---|---|---|
| ||
{
"typeId": "api",
"category": "product",
"apiId": "read",
"apiName": "상품 조회",
"apiType": "service",
"method": "GET",
"parameters": [
],
"aggregation": true,
"config": [
{
"configId": "viewCount",
"tid": "product",
"type": "event",
"allowParams": false,
"orderNo": 1,
"event": "increaseViewCount"
},
{
"configId": "root",
"tid": "siteProduct",
"type": "query",
"resultType": "OBJECT",
"query": [
{
"method": "matching",
"field": "id",
"value": "{{:productId}}"
}
],
"response": [
]
}
]
} |
parameters
API 파라미터 설정은 호출하는 파라미터를 제한하고 필수 파라미터를 정의한다.
pid | valueType | description | |
|---|---|---|---|
id | INT | 자동 생성 ID아이디 | |
targetIdparameter | REFERENCE | 해당 API 설정 | |
field | STRING | 응답 필드 명 | |
type | CODE | 응답 필드 유형
| |
value | STRING | 매핑 값, EL 사용 가능 | |
config | CHILDREN | type이 config인 경우 하위 API Config 설정STRING | 호출 파라미터 |
name | STRING | 파라미터 명칭 | |
required | BOOLEAN | 필수 여부 | |
valueType | CODE | 파라미터 값 유형(String, Number, File, Object, Array) | |
description | TEXT | 설명 |
Sample "required": true
| Code Block |
|---|
{
"typeId": "api",
"category": "product",
"apiId": "read",
"apiName": "상품 조회",
"apiType": "service",
"method": "GET",
"parameters": [
{
"parameter": "productId",
"name": "상품ID",
"valueType": "STRING",
"required": true
}
]
} |
| Code Block |
|---|
{
"result": "400",
"resultMessage": "Required Parameter : productId"
} |