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	호출 파라미터 정의
root	PART	aggregation이 false인 경우 단독 apiConfig 설정
config	CHILDREN	aggregation이 true인 경우 다중 apiConfig 설정

method

API 호출 Method
POST, GET, PUT, DELETE, PATCH

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

{
    "result": "405",
    "resultMessage": "허용하지 않는 Method 입니다."
}

→ GET

{
    "time": "2020-10-21T08:45:32.321+0000",
    "result": "200",
    "resultMessage": "SUCCESS",
    "item": {
        "id": 1323881205,
        "name": "[LG전자] X2 자급제폰(32GB)",


  ...
  
}

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

apiAuthority

secure

SSL만 허용 여부

{
    "result": "500",
    "resultMessage": "허용하지 않는 Protocol 입니다."
}

signed

로그인된 사용자만 허용 여부

{
    "result": "401",
    "resultMessage": "로그인이 필요합니다."
}

aggregation

하나 이상의 apiConfig를 이용하여 여러 API를 조합하여 실행할지를 결정

root

aggregation이 false인 경우 단독 apiConfig 설정

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

{
  "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	자동 생성 아이디
parameter	STRING	호출 파라미터
name	STRING	파라미터 명칭
required	BOOLEAN	필수 여부
valueType	CODE	파라미터 값 유형(String, Number, File, Object, Array)
description	TEXT	설명

Sample "required": true

{
  "typeId": "api",
  "category": "product",
  "apiId": "read",
  "apiName": "상품 조회",
  "apiType": "service",
  "method": "GET",
  "parameters": [
    {
      "parameter": "productId",
      "name": "상품ID",
      "valueType": "STRING",
      "required": true
    }
  ]
}

{
    "result": "400",
    "resultMessage": "Required Parameter : productId"
}