api

API 설정은 API 호출에 대한 형식을 정의하며, 실제 API의 동작은 apiConfig로 정의한다.

하나의 API는 여러개의 API Config를 설정함으로써 API GW의 Aggregation 기능을 제공한다.

{{protocol}}://{{hostname}}:{{port}}/{{apiType}}/{{apiCategory}}/{{api}}

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

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	로그인된 사용자만 허용 여부
aggregation	BOOLEAN	하나 이상의 apiConfig를 이용하여 여러 API를 조합하여 실행할지를 결정
statistic	BOOLEAN	해당 API를 통계에 사용할지를 결정, false일 경우 API 로그에 7일만 보관되고 삭제
parameters	CHILDREN	호출 파라미터 정의
config	CHILDREN	실제 API 동작 설정

apiType

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

▪ service

FrontOffice에서 사용하는 API
Path : svc

{{protocol}}://{{hostname}}:{{port}}/svc/{{apiCategory}}/{{api}}?_siteId=dxp

_siteId 항상 필수
자동 생성 API 사용 불가능. 설정 API 만 사용 가능.
인증 : Customer의 세션을 사용한다.

GET {{protocol}}://{{hostname}}:{{port}}/auth/svc/jwt?_siteId=dxp

▪ admin

Admin 사용자용 BackOffice를 위한 API
Path : adm

{{protocol}}://{{hostname}}:{{port}}/adm/{{nodeType}}/{{event}}

{{protocol}}://{{hostname}}:{{port}}/adm/{{apiCategory}}/{{api}}

인증 : 반드시 로그인된 Admin 사용자만 사용 가능

GET {{protocol}}://{{hostname}}:{{port}}/auth/adm/jwt

POST {{protocol}}://{{hostname}}:{{port}}/adm/signIn

▪ manager

Manger 사용자용 BackOffice를 위한 API
Path : mng

{{protocol}}://{{hostname}}:{{port}}/mng/{{nodeType}}/{{event}}

{{protocol}}://{{hostname}}:{{port}}/mng/{{apiCategory}}/{{api}}

인증 : 반드시 로그인된 Manager 사용자만 사용 가능

GET {{protocol}}://{{hostname}}:{{port}}/auth/mng/jwt

POST {{protocol}}://{{hostname}}:{{port}}/mng/signIn

▪ external

외부 또는 레거시 시스템과 연동을 위해서 사용하는 API
Path : ext

{{protocol}}://{{hostname}}:{{port}}/ext/{{nodeType}}/{{event}}

{{protocol}}://{{hostname}}:{{port}}/ext/{{apiCategory}}/{{api}}

인증 : API 키를 통해서 인증

▪ internal

ICE 내부 서비스간 연동을 위해서 사용하는 API
Path : int

{{protocol}}://{{hostname}}:{{port}}/int/{{nodeType}}/{{event}}

{{protocol}}://{{hostname}}:{{port}}/int/{{apiCategory}}/{{api}}

인증 : 클러스터에 등록된 서버들만 통신 가능

▪ open

오픈 API에 사용
Path : api

{{protocol}}://{{hostname}}:{{port}}/api/{{nodeType}}/{{event}}

{{protocol}}://{{hostname}}:{{port}}/api/{{apiCategory}}/{{api}}

자동 생성 API 사용 불가능. 설정 API 만 사용 가능.

인증 : API Key를 이용한 인증 사용, 요구사항에 따라서 인증 방식 확장이 가능(OAuth 등)

{{protocol}}://{{hostname}}:{{port}}/api/testEvent/list

{
    "timestamp": "2020-10-20T02:45:39.969+0000",
    "status": 400,
    "error": "Bad Request",
    "message": "Required String parameter 'apiKey' is not present",
    "path": "/api/testEvent/list"
}

{{protocol}}://{{hostname}}:{{port}}/api/testEvent/list?apiKey=W2!G*LgUu?5*!c*VubLVsfVyW42t$KHt

{
    "result": "200",
    "resultMessage": "SUCCESS",
    "totalCount": 0,
    "totalTypeCount": 0,
    "resultCount": 0,
    "items": []
}

apiType은 apiCategory 와 api 에 각각 설정 가능하다.

apiCategory 설정되어있고 api에 설정 안되어있으면 하위 api 는 apiCategory의 apiType을 따른다.
apiCategory와 하위 api에 서로다른 apiType이 설정되어 있는 경우 api 는 자신의 apiType을 따른다.

[apiCategory] apiType : null, [api] apiType : service

{
  "typeId": "apiCategory",
  "id": "product",
  "categoryName": "product API",
  "dateFormat": "yyyy-MM-dd HH:mm:ss",
  "fileUrlFormat": {
    "default": "{{:getEnvValue('core.cluster.api-url-prefix')}}"
  },
  "commonParameters": [
  ],
  "commonResponse": [
  ]
}

{
  "typeId": "api",
  "category": "product",
  "apiId": "list",
  "apiName": "Product List",
  "apiType": "service",
  "method": "GET",
  "parameters": [
  ],
  "config": {
    ...
  }
}

{{protocol}}://{{hostname}}:{{port}}/svc/product/list?_siteId=dxp

[apiCategory] apiType : service, [api] apiType : null

{
  "typeId": "apiCategory",
  "id": "product",
  "categoryName": "product API",
  "apiType": "service",
  "dateFormat": "yyyy-MM-dd HH:mm:ss",
  "fileUrlFormat": {
    "default": "{{:getEnvValue('core.cluster.api-url-prefix')}}"
  },
  "commonParameters": [
  ],
  "commonResponse": [
  ]
}

{
  "typeId": "api",
  "category": "product",
  "apiId": "list",
  "apiName": "Product List",
  "apiType": "",
  "method": "GET",
  "parameters": [
  ],
  "config": {
    ...
  }
}

{{protocol}}://{{hostname}}:{{port}}/svc/product/list?_siteId=dxp

[apiCategory] apiType : service, [api] apiType : admin

{
  "typeId": "apiCategory",
  "id": "product",
  "categoryName": "product API",
  "apiType": "service",
  "dateFormat": "yyyy-MM-dd HH:mm:ss",
  "fileUrlFormat": {
    "default": "{{:getEnvValue('core.cluster.api-url-prefix')}}"
  },
  "commonParameters": [
  ],
  "commonResponse": [
  ]
}

{
  "typeId": "api",
  "category": "product",
  "apiId": "list",
  "apiName": "Product List",
  "apiType": "admin",
  "method": "GET",
  "parameters": [
  ],
  "config": {
    ...
  }
}

{{protocol}}://{{hostname}}:{{port}}/adm/product/list

parameters

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

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

API Response

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

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

Result Code

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

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

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

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