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

...

pid

...

valueType

...

description

...

id

...

INT

...

자동 생성 아이디

...

targetId

...

PARENT

...

상위 API

...

configId

...

STRING

...

동일 API에 여러개의 apiConfig가 설정되는 경우 API 응답 명칭을 의미, ROOT로 설정하는 경우 응답의 최상위에 해당 apiConfig 결과가 Merge

...

type

...

CODE

...

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,select,method`) 대상 Node Type
resultType	CODE	응답 형태(array, object, none, page)
relayUrl	STRING	중계할 API URL
relayMethod	CODE	중계 API 호출 메소드 (GET, POST...)
datasource	REFERENCE	Select 일경우 사용할 데이터소스
sql	TEXT	Select 쿼리 SQL
method	STRING	Method일 경우 실행할 메소드 service.method 형식
process	REFERENCE	Process 일 경우 실핼할 ProcesFlow 선택
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)
customFilter	STRING
customResponse	STRING	응답 결과에 대한 추가적인 처리가 필요한 경우 해당 서비스 정의
event	REFERENCE
failOver	CODE	타임아웃이 발생하거나 500번대 에러가 발생하는 경우 이에 대한 처리
compensatingAPI	REFERENCE	failOver가 compensating일 경우 보상 API 지정
query	PARTS	Query인 경우 해당하는 query 설정을 등록
data	CHILDREN	해당 API Config를 호출하기 위한 파라미터를 재정의
relayType	CODE	Relay 유형
relayAuth	REFERENCE	Relay 시 사용할 API 인증 유형을 선택
relayHeader	PARTS	Relay 시 Rquest Header에 필요한 항목을 설정
bodyType	CODE	Relay 시 Requst Body의 유형(form/raw)
relayParameters	PARTS	bodyType이 form 인 경우 API 호출에 사용되는 파라미터 설정
relayBody	TEXT	bodyType이 raw 인 경우 API 호출에 사용되는 Request Body 설정
response	CHILDREN	해당 API Config의 응답 필드에 대한 정의
orderNo	INT	API Config 실행 순서

apiConfig 공통 항목

resultType

...

cacheKey api::snack>list?&name.matching=오레오 에 대하여 아래 response가 캐시에 저장된다.

Code Block

{{protocol}}://{{hostname}}:{{port}}/svc/snack/list?_siteId=bestshop&name=오레오

{
    "result": "200",
    "resultMessage": "SUCCESS",
    "totalCount": 1,
    "totalTypeCount": 20,
    "resultCount": 1,
    "items": [
        {
            "id": "103",
            "label": "오레오",
            "name": "오레오"
        }
    ]
}

cache hit out log

Code Block
n.ion.ice.core.context.ContextUtils : cache hit fail : api::snack>list?&name.matching=오레오

"cacheable": true 이면 아래 항목 설정 가능

cacheTime

캐시 시간(초)

캐시 시간이 도래하면 캐시가 삭제된다.

캐시 시간 중에는 데이터가 수정되어도 캐시된 응답결과에 반영되지 않는다.

"cacheable": true 이면 cacheTime 설정 필수

keepCache

캐시 유지 여부

주기적으로 호출하여 캐시를 유지 시킨다.

>>얼만큼의 주기인지 확인 예정<<

excludeCacheKey

캐시키에서 제외할 파라미터 목록(예: timeStamp,userId)

allowParams

파라미터 쿼리에 대한 허용 여부

default : false

파라미터 쿼리란?
schema 정의가 되어있는 데이터 리스트에 대하여 파라미터로 쿼리 검색이 가능하도록 API 기능을 지원하고 있다.

Expand

title	apiConfig에 allowParams = true

Code Block

{{protocol}}://{{hostname}}:{{port}}/svc/snack/list?_siteId=bestshop&name=오레오

{
    "result": "200",
    "resultMessage": "SUCCESS",
    "totalCount": 1,
    "totalTypeCount": 20,
    "resultCount": 1,
    "items": [
        {
            "id": "103",
            "label": "오레오",
            "name": "오레오"
        }
    ]
}

cache hit out log

Code Block
n.ion.ice.core.context.ContextUtils : cache hit fail : api::snack>list?&name.matching=오레오

"cacheable": true 이면 아래 항목 설정 가능

cacheTime

캐시 시간(초)

캐시 시간이 도래하면 캐시가 삭제된다.

캐시 시간 중에는 데이터가 수정되어도 캐시된 응답결과에 반영되지 않는다.

"cacheable": true 이면 cacheTime 설정 필수

keepCache

캐시 유지 여부

주기적(1분)으로 호출하여 캐시를 유지 시킨다.

(keepCache 처리량에 따라 1분이상 딜레이 될 수 있다.)

excludeCacheKey

캐시키에서 제외할 파라미터 목록(예: timeStamp,userId)

allowParams

파라미터 쿼리에 대한 허용 여부

default : false

파라미터 쿼리란?
schema 정의가 되어있는 데이터 리스트에 대하여 파라미터로 쿼리 검색이 가능하도록 API 기능을 지원하고 있다.

Expand

title	apiConfig에 allowParams = true

Code Block

{
  "typeId": "api",
  "category": "snack",
  "apiId": "list",
  "apiName": "snack List",
  "apiType": "service",
  "method": "GET",
  "parameters": [
  ],
  "statistic": true,
  "aggregation": false,
  "root": {
    "configId": "root",
    "tid": "snack",
    "type": "query",
    "allowParams" : true,
    "query": [
    ],
    "response": [
      {
        "field": "_all_",
        "type": "all"
      }
    ]
  }
}

name_matching=오레오 쿼리 검색 성공

Code Block

{{protocol}}://{{hostname}}:{{port}}/svc/snack/list?_siteId=bestshop&name_matching=오레오

{
    "result": "200",
    "resultMessage": "SUCCESS",
    "totalCount": 1,
    "totalTypeCount": 18,
    "resultCount": 1,
    "items": [
        {
            "id": "103",
            "label": "오레오",
            "name": "오레오"
        }
    ]
}

Expand

title	apiConfig에 allowParams = false

Code Block

{
  "typeId": "api",
  "category": "snack",
  "apiId": "list",
  "apiName": "snack List",
  "apiType": "service",
  "method": "GET",
  "parameters": [
  ],
  "statistic": true,
  "aggregation": false,
  "root": {
    "configId": "root",
    "tid": "snack",
    "type": "query",
    "allowParams" : false,
    "query": [
    ],
    "response": [
      {
        "field": "_all_",
        "type": "all"
      }
    ]
  }
}

name_matching=오레오 쿼리 검색 실패

Code Block

{{protocol}}://{{hostname}}:{{port}}/svc/snack/list?_siteId=bestshop&name_matching=오레오

{
    "result": "200",
    "resultMessage": "SUCCESS",
    "totalCount": 18,
    "totalTypeCount": 18,
    "resultCount": 18,
    "items": [
        {
            "id": "101",
            "label": "꼬깔콘",
            "name": "꼬깔콘"
        },
        {
            "id": "102",
            "label": "빠다 코코낫",
            "name": "빠다 코코낫"
        },
        {
            "id": "103",
            "label": "오레오",
            "name": "오레오"
        },
        {
            "id": "104",
            "label": "쿠크다스",
            "name": "쿠크다스"
        }

        ...
        
        
    ]
}

if

해당 apiConfig에 대한 실행 여부 테스트(EL 사용) {{:equals(siteId, ‘dxp’)}}

connectTimeout

대상 서비스의 커넥션 타임아웃 설정 ms (default : 5000)

readTimeout

대상 서비스의 응답 타임아웃 설정 ms (default : 10000)

failOver

타임아웃이 발생하거나 500번대 에러가 발생하는 경우 이에 대한 처리

none : 에러 응답 리턴

retry : 재시도

last : 마지막 응답 결과 전송

compensating : 보상 API 호출

compensatingAPI

failOver가 compensating일 경우 보상 API 지정

customResponse

apiConfig 동작의 응답 결과를 조작할 수 있다.

추가적인 처리가 필요한 경우 해당 서비스 정의를 해야한다.

아래는 응답결과에 idx 필드를 추가하는 사례이다.

Class 추가
- location : net/ion/ice/core/context/response
- implements CustomResponse 하는 class 를 하나 생성한다.
@Component 어노테이션 추가
- @Component("sampleResponse")
customResponse 작성

Code Block

language	java

@Component("sampleResponse")
public class SampleResponse implements CustomResponse {
    @Override
    public List<QueryResult> execute(QueryContext queryContext, List<QueryResult> subList) {
        int idx = 1;

        //subList : apiConfig 동작의 응답 결과 리스트
        
        for(QueryResult item : subList){
          item.put("idx", idx++);
        }

        return subList;
    }

    @Override
    public Map<String, Object> execute(ReadContext readContext, Map<String, Object> itemResult) {

        return itemResult;
    }
}

apiConfig에 customResponse 세팅
- @Component 어노테이션 명으로 작성한다.

Code Block

{
  "typeId": "api",
  "category": "snack",
  "apiId": "list",
  "apiName": "snack List",
  "apiType": "service",
  "method": "GET",
  "parameters": [
  ],
  "statistic": true,
  "aggregation": false,
  "root": {
    "configId": "root",
    "tid": "snack",
    "type": "query",
    "allowParams": true,
    "customResponse":

...

"sampleResponse",
    "query": [
    ],
    "response": [
      {
        "field": "_all_",
        "type": "all"
      }
    ]
  }
}

name_matching=오레오 쿼리 검색 성공 api 응답결과에 idx가 추가된것을 볼수 있다.

Code Block
{{protocol}}://{{hostname}}:{{port}}/svc/snack/list?_siteId=bestshop&

...

limit=

...

2

{
    "result": "200",
    "resultMessage": "SUCCESS",
    "totalCount":

...

 20,
    "totalTypeCount":

...

 20,
    "resultCount":

...

 2,
    "more": true,
    "moreCount": 10,
    "items": [
        {
            "id": "

...

104",
            "label": "

...

쿠크다스",
            "name": "

...

쿠크다스",
            "idx": 1
        }

...

title	apiConfig에 allowParams = false

...

,
        {
            "id": "103",
            "label": "오레오",
            "name": "오레오",
            "idx": 2
        }
    ]
}

response

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

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 설정

response type

Expand

title	all : 전체 응답 필드를 바이패스

Code Block
{ "typeId": "api", "category": "snack",

...

apiId": "

...

list",

...

apiName":

...

"snack

...

List",

...

apiType":

...

"service",

...

"method": "GET",

...

parameters": [

...

],
  "

...

statistic":

...

name_matching=오레오 쿼리 검색 실패

...

true,
  "aggregation": false,
  "root": {
    "configId": "root",
    "tid": "snack",
    "type": "query",
    "query": [
      {
        "method": "matching",
        "field": "name",
        "value": "{{:name}}"
      }
    ],
    "response": [
      {
        "field": "_all_",
        "type": "all"
      }
    ]
  }
}

Code Block
{ "result": "200", "resultMessage": "SUCCESS", "totalCount": 1, "totalTypeCount": 20, "resultCount": 1, "items": [ { "id": "

...

103",
            "label": "

...

오레오",
            "name": "

...

오레오"
        }

...

해당 apiConfig에 대한 실행 여부 테스트(EL 사용) {{:equals(siteId, ‘dxp’)}}

...

대상 서비스의 커넥션 타임아웃 설정 ms (default : 5000)

...

대상 서비스의 응답 타임아웃 설정 ms (default : 10000)

failOver

타임아웃이 발생하거나 500번대 에러가 발생하는 경우 이에 대한 처리

none : 에러 응답 리턴

retry : 재시도

last : 마지막 응답 결과 전송

compensating : 보상 API 호출

...

failOver가 compensating일 경우 보상 API 지정

...

apiConfig 동작의 응답 결과를 조작할 수 있다.

추가적인 처리가 필요한 경우 해당 서비스 정의를 해야한다.

...

title	아래는 응답결과에 idx 필드를 추가하는 사례이다.

implements CustomResponse 하는 class 를 하나 작성한다.

...

language	java

...

]
}

Expand

title	field : fieldId와 동일한 응답 항목 매핑

지정한 field로 응답결과를 구성할 수 있다.

Code Block

{
  "typeId": "api",
  "category": "snack",
  "apiId": "list",
  "apiName": "snack List",
  "apiType": "service",
  "method": "GET",
  "parameters": [
  ],
  "statistic": true,
  "aggregation": false,
  "root": {
    "configId": "root",
    "tid": "snack",
    "type": "query",
    "query": [
      {
        "method": "matching",
        "field": "name",

...

 "value":

...

"{{:name}}"
      }
    ],
    "response": [

...

"field": "id",

...

"type": "field",
        "value": ""

...

     }
    ]

...

}
}

Code Block
{

...

apiConfig에 customResponse 설정

    "result": "200",
    "resultMessage": "SUCCESS",
    "totalCount": 1,
    "totalTypeCount": 20,
    "resultCount": 1,
    "items": [
        {
            "id": "103"
        }
    ]
}

Expand

title	config : 하위에 다른 API 결과를 조합하여 응답을 생성

snack 응답결과에 snackScore 쿼리 결과를 조합하는 사례

Code Block
{ "typeId": "api", "category": "snack", "apiId": "list", "apiName": "snack List", "apiType": "service", "method": "GET", "parameters": [ ], "statistic":

...

 true,
  "aggregation": false,
  "root": {
    "configId": "root",
    "tid": "snack",
    "type": "query",
    "

...

query": [

...

 {
        "

...

method": "

...

matching",
        "

...

field": "

...

name",
        "

...

value": "

...

{{:name}}"

...

 ],
    "

...

response": [

...

"field": "id",
        "

...

type": "

...

field",
        "

...

value": "

...

"
      },

...

api 응답결과에 idx가 추가된것을 볼수 있다.

Code Block

{{protocol}}://{{hostname}}:{{port}}/svc/snack/list?_siteId=bestshop&limit=2
{
    "result": "200",
    "resultMessage": "SUCCESS",
    "totalCount": 20,
    "totalTypeCount": 20,
    "resultCount": 2,
    "more": true,
    "moreCount": 10,
    "items": [
        {
            "id": "104",
            "label": "쿠크다스",
            "name": "쿠크다스",
            "idx": 1
        },
        {
            "id": "103",
            "label": "오레오",
            "name": "오레오",
            "idx": 2
        }
    ]
}

response

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

...

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 설정

response type

Expand

title	all

Code Block

{
  "typeId": "api",
  "category        "field": "name",
        "type": "field",
        "value": ""
      },
      {
        "field": "scoreList",
        "type": "config",
        "config": [
          {
            "tid": "snackScore",
            "type": "query",
            "query": [
              {
                "method": "sorting",
                "value": "score desc"
              },
              {
                "method": "matching",
                "field": "snack",
  "apiId": "list",     "apiName": "snack List",   "apiType": "service",   "methodvalue": "GET",{{:id}}"
     "parameters": [   ],   "statistic": true, }
 "aggregation": false,   "root": {     "configId": "root" ],
    "tid": "snack",        "typeresponse": "query",[
    "query": [       {  {
      "method": "matching",         "field": "name",id",
                "valuetype": "{{:name}}"field",
      }     ],     "responsevalue": [""
      {         "field": "_all_"},
        "type": "all"     {
 }     ]   } }

Code Block

{     "result": "200",     "resultMessage": "SUCCESS",
    "totalCount": 1,
    "totalTypeCount": 20,
    "resultCount": 1,
    "items": [
        {
            "id": "103",
            "label": "오레오",
            "name": "오레오"
        }
    ]
}

Expand

title	field

Code Block

{
  "typeId": "api",
  "category": "snack",
  "apiId": "list",
  "apiName": "snack List",
  "apiType": "service",
  "method": "GET",
  "parameters": [
  ],
  "statistic": true,
  "aggregation": false,
  "root": {
    "configId": "root",
    "tid": "snack",
    "type": "query",
    "query": [
      {
         "field": "score",
                "type": "field",
                "value": ""
              }
            ]
          }
        ]
      }
    ]
  }
}

"field": "scoreList" 에 snackScore 쿼리 결과

snackScore 쿼리에서 {{:id}} 는 상위 snack 응답결과의 id로 치환되었다.

Code Block


{
  "method": "matching",
     
  "field": "namesnack",
  
     "value": "{{:nameid}}"
      }
    ],
    "response": [
      {
        "field": "id",
        "type": "field",
        "value": ""
      }
    ]
  }
}

Code Block

{
    "result": "200",
    "resultMessage": "SUCCESS",
    "totalCount": 1,
    "totalTypeCount": 20,
    "resultCount": 1,
    "items": [
        {
            "id": "103"}

Code Block

{
    "result": "200",
    "resultMessage": "SUCCESS",
    "totalCount": 1,
    "totalTypeCount": 20,
    "resultCount": 1,
    "items": [
        {
            "id": "101",
            "name": "꼬깔콘",
            "scoreList": [
                {
                    "id": 1,
                    "score": 5
                },
                {
                    "id": 2,
                    "score": 5
                },
                {
                    "id": 3,
                    "score": 4
                }
            ]
        }
    ]
}

Expand

title	position

Expand

title	mapping

type별 사용 가능한 항목

	Query	Event	Select	Relay	Read	Reads	Form	Method	Process
id
targetId
configId
type
tid	O	O	O		O	O	O	O
resultType
relayUrl				O
relayMethod				O
datasource			O
sql			O
method								O
process									O
cacheable
cacheTime
keepCache
excludeCacheKey
allowParams
if
connectTimeout
readTimeout
customFilter	O
customResponse
event		O
failOver
compensatingAPI
query	O
data		O	O		O	O
relayType				O
relayAuth				O
relayHeader				O
bodyType				O
relayParameters				O
relayBody				O
response
orderNo

Version	Old Version 15	New Version Current
Changes made by	Hannah	Hannah
Saved on	Oct 22, 2020	Apr 18, 2022

Page Comparison

Versions Compared

Key

apiConfig 공통 항목

resultType

allowParams

allowParams

if

connectTimeout

readTimeout

failOver

compensatingAPI

customResponse

response

failOver

response

type별 사용 가능한 항목

Query

Event

Select

Relay

Read

Reads

Form

Method

Process

Response

id

targetId

configId

type

tid

resultType

relayUrl

relayMethod

datasource

sql

method

process

cacheable

cacheTime

keepCache

excludeCacheKey

allowParams

if

connectTimeout

readTimeout

customFilter

customResponse

event

failOver

compensatingAPI

query

data

relayType

relayAuth

relayHeader

bodyType

relayParameters

relayBody

response

orderNo