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)
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

응답 형태(array, object, none, page)

>>type별 resultType defulat<<

>>type별 사용가능 resultType<<

cacheable

API 요청에 대하여 응답결과를 캐시에 저장하고 설정한 시간동안 캐시 데이터를 반환한다.

default : false

캐시에 저장하려면 캐시키를 구성하기 위한 한개이상의 파라미터 쿼리 검색어가 필요하다.

cacheKey 란?
캐시에 저장할 response에 대한 유일키. api와 파라미터 쿼리를 조합하여 키가 만들어진다.
api::snack>list?&name.matching=오레오

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

{{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

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 기능을 지원하고 있다.

apiConfig에 allowParams = true

{
  "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=오레오 쿼리 검색 성공

{{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": "오레오"
        }
    ]
}

apiConfig에 allowParams = false

{
  "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=오레오 쿼리 검색 실패

{{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 추가
- implements CustomResponse 하는 class 를 하나 생성한다.
@Component 어노테이션 추가
- @Component("sampleResponse")
customResponse 작성

@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 어노테이션 명으로 작성한다.

{
  "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"
      }
    ]
  }
}

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

{{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

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

{
  "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": "_all_",
        "type": "all"
      }
    ]
  }
}

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

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

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

{
  "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": ""
      }
    ]
  }
}

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

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

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

{
  "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": ""
      },
      {
        "field": "name",
        "type": "field",
        "value": ""
      },
      {
        "field": "scoreList",
        "type": "config",
        "config": [
          {
            "tid": "snackScore",
            "type": "query",
            "query": [
              {
                "method": "sorting",
                "value": "score desc"
              },
              {
                "method": "matching",
                "field": "snack",
                "value": "{{:id}}"
              }
            ],
            "response": [
              {
                "field": "id",
                "type": "field",
                "value": ""
              },
              {
                "field": "score",
                "type": "field",
                "value": ""
              }
            ]
          }
        ]
      }
    ]
  }
}

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

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

{
  "method": "matching",
  "field": "snack",
  "value": "{{:id}}"
}

{
    "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
                }
            ]
        }
    ]
}

position

mapping

type별 사용 가능한 항목

	Query	Event	Select	Relay	Read	Reads	Form	Method	Process
id
targetId
configId
type
tid	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

apiConfig

apiConfig 공통 항목

resultType

cacheable

allowParams

if

connectTimeout

readTimeout

failOver

compensatingAPI

customResponse

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