API 설정은 API 호출에 대한 형식을 정의하며, 실제 API의 동작은 apiConfig로 정의한다.
...
| Info |
|---|
{{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실제 API 동작 설정 | 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 | 자동 생성 아이디 |
parameter | STRING | 호출 파라미터 |
name | STRING | 파라미터 명칭 |
required | BOOLEAN | 필수 여부 |
valueType | CODE | 파라미터 값 유형(String, Number, File, Object, Array) |
description | TEXT | 설명 |
API Response
ICE의 API Response는 result와 resultMessage를 항상 포함하고 있으며, 다른 필드는 API 설정에 따라서 변경된다.
...
Sample "required": true
| Code Block |
|---|
{ "typeId": "api", "category": "product", "apiId": "200read", "apiName": "상품 조회", "resultMessageapiType": "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
...
service",
"method": "GET",
"parameters": [
{
"parameter": "productId",
"name": "상품ID",
"valueType": "STRING",
"required": true
}
]
} |
| Code Block |
|---|
{
"result": "400",
"resultMessage": "Required Parameter : productId"
} |