API Gateway 서비스는 API Gateway를 통해 서비스할 API를 관리하는 단위입니다. API Gateway 서비스마다 하나의 API 리소스와 여러 개의 스테이지를 관리할 수 있으며, 대시보드를 통해 API 지표를 확인할 수 있습니다.
API Gateway 서비스 정보를 입력한 후 생성 버튼을 클릭하면 API Gateway 서비스가 생성됩니다.
[참고] API Gateway 서비스 생성 개수 제한
API Gateway 서비스는 프로젝트당 최대 10개까지 생성 가능합니다.
[주의] API Gateway 서비스를 삭제할 수 없는 경우
API Gateway 서비스의 스테이지와 연결된 사용량 계획이 존재하면 API Gateway 서비스를 삭제할 수 없습니다.
리소스는 API Gateway를 통해 서비스할 API를 설계하는 화면입니다. 모든 API 요청 클라이언트는 API Gateway 리소스에 정의된 API에 대해 요청을 할 수 있습니다. 리소스는 API의 리소스 경로와 메서드를 관리합니다.
Swagger v2.0 OpenAPI Specification 형식의 파일로 리소스를 가져올 수 있습니다. 1. 리소스 가져오기 버튼을 클릭합니다. 2. Swagger 파일 선택 버튼을 클릭하여 파일을 선택하거나 Swagger 내용을 직접 입력합니다. 3. 적용 버튼을 클릭합니다.
[주의] 리소스 가져오기 시 기존 리소스와 모델 덮어쓰기
리소스를 가져오면 기존의 리소스는 삭제되고 가져온 리소스로 덮어씁니다. 리소스를 가져오면 해당 서비스에 생성되어 있던 기존의 모델은 모두 삭제되고 가져온 모델로 덮어씁니다.[참고] 2021-11-23 이전 스테이지 내보내기(Export) 파일의 가져오기 실패
2021-11-23 이전에 스테이지 내보내기를 통해 다운로드한 파일로 리소스 가져오기를 하는 경우 실패가 발생할 수 있습니다. 스테이지 내보내기를 통해 새로 생성된 파일을 이용하여 리소스 가져오기를 이용하시거나 다음의 작업을 통해 기존 파일을 변경하시기 바랍니다. 변경 작업 1. 파일 내 x-api-nhn-apigateway > plugins의 플러그인 설정 문자열을 JSON 객체로 변환해야 합니다. 2. 파일 내 리소스 메서드 > x-api-nhn-apigateway > plugins에 CORS 플러그인 설정 문자열이 존재할 경우 제거해야 합니다. 리소스 메서드에는 CORS 플러그인을 설정할 수 없으며, 해당 상위 리소스 경로에 CORS 플러그인이 설정되어 있을 경우 리소스 가져오기 시 자동으로 추가됩니다. 가이드 내용으로 해결이 안 되는 경우 고객 센터로 문의해주시기 바랍니다.
- [예시1] 가져오기 실패: 2021-11-23 이전 스테이지 내보내기 파일의 경우 plugins의 플러그인 설정값이 JSON 형식의 문자열로 구성됨
{
...
"x-nhncloud-apigateway": {
"plugins": {
"HTTP": "{\"frontendEndpointPath\":\"/{proxy+}\",\"backendEndpointPath\":\"/anything/${request.path.proxy+}\"}",
}
}
...
}
- [예시1] 가져오기 성공: plugins의 플러그인 설정값에서 JSON 형식의 문자열을 JSON 객체로 수정한 스테이지 내보내기 파일
{
...
"x-nhncloud-apigateway": {
"plugins": {
"HTTP": {
"frontendEndpointPath": "/{proxy+}",
"backendEndpointPath": "/anything/${request.path.proxy+}"
}
}
}
...
}
- [예시2] 가져오기 실패: 2021-11-23 이전 스테이지 내보내기 파일의 경우 리소스 경로에 CORS 플러그인이 설정되어 있을 경우 하위 리소스 메서드에 CORS 플러그인 설정값이 포함되어 있음
{
...
"paths": {
"/anything": {
"get": {
...
"x-nhncloud-apigateway": {
"plugins": {
"MOCK": {
"statusCode": 200
},
"CORS": {
"allowedMethods": ["GET", "POST", "DELETE", "PUT", "OPTIONS", "HEAD", "PATCH"],
"allowedHeaders": ["*"],
"allowedOrigins": ["*"],
"exposedHeaders": [],
"maxCredentialsAge": null,
"allowCredentials": false
}
}
}
},
"options": {
"summary": "CORS",
...
},
"x-nhncloud-apigateway": {
"plugins": {
"CORS": {
"allowedMethods": ["GET", "POST", "DELETE", "PUT", "OPTIONS", "HEAD", "PATCH"],
"allowedHeaders": ["*"],
"allowedOrigins": ["*"],
"exposedHeaders": [],
"maxCredentialsAge": null,
"allowCredentials": false
}
}
}
}
}
...
}
- [예시2] 가져오기 성공: 리소스 메서드에 CORS 플러그인 설정값을 제거한 스테이지 내보내기 파일
{
...
"paths": {
"/anything": {
"get": {
...
},
"options": {
"summary": "CORS",
...
},
"x-nhncloud-apigateway": {
"plugins": {
"CORS": {
"allowedMethods": ["GET", "POST", "DELETE", "PUT", "OPTIONS", "HEAD", "PATCH"],
"allowedHeaders": ["*"],
"allowedOrigins": ["*"],
"exposedHeaders": [],
"maxCredentialsAge": null,
"allowCredentials": false
}
}
}
}
}
...
}
백엔드 엔드포인트 타입: 사용자 정의 응답
플러그인: 선택된 경로에 추가된 플러그인을 생성된 메서드에도 추가하려면 체크합니다.
[참고] 리소스 메서드 생성 제한 개수
메서드는 모든 리소스 경로를 포함하여 최대 100개까지 생성 가능합니다.
[참고] CORS 플러그인에 의해 등록된 OPTIONS 메서드의 수정
CORS 플러그인에 의해 등록된 OPTIONS 메서드는 수정할 수 없습니다.
[주의] 리소스 경로 삭제
리소스 경로를 삭제하면 선택된 리소스의 경로의 하위 리소스 경로와 메서드가 모두 삭제 됩니다.[참고] CORS 플러그인에 의해 등록된 OPTIONS 메서드의 삭제
CORS 플러그인에 의해 등록된 OPTIONS 메서드는 삭제할 수 없습니다.
리소스를 변경한 후 스테이지에 변경된 리소스를 적용하려면 스테이지 리소스 적용을 해야 합니다.
[주의] 스테이지 리소스 적용
- 스테이지 리소스를 적용하려면 적어도 하나 이상의 스테이지가 존재해야 합니다. - 스테이지에 리소스가 적용된 후에는 기존 리소스로 복구가 불가합니다. - 이미 스테이지에 최신 리소스가 적용되어 있으면 스테이지 리소스 적용이 불가합니다.
플러그인을 통해 API Gateway에서 제공하는 부가 기능을 추가할 수 있습니다.
[주의] 플러그인 추가 후 변경사항 저장
플러그인을 추가한 후 변경 사항 저장 버튼을 클릭해야 설정이 저장됩니다.
리소스 메서드별 요청 파라미터와 응답 형식, 콘텐츠 타입을 설정합니다. 설정한 내용은 API 설명서에 적용됩니다.
HTTP 응답 상태 코드별 헤더와 요청 본문 항목과 콘텐츠 타입을 설정합니다. 설정한 내용은 API 설명서에 적용됩니다.
리소스의 메서드 생성 및 플러그인 설정 시 아래 정의된 변수를 사용할 수 있습니다.
| 컨텍스트 변수 | 설명 |
|---|---|
| ${request.clientIp} | 요청 클라이언트의 IP |
| ${request.path.variable-name} | 리소스에서 선언한 단일 경로 변수 {variable-name} 값 |
| ${request.path.variable-name+} | 리소스에서 선언한 하위 경로를 포함한 경로 변수 {variable-name+} 값 |
| ${request.host} | 요청 Host 헤더(예: kr1-example.api.nhncloudservice.com) |
| ${request.uri} | 요청 URI(예: https://kr1-example.api.nhncloudservice.com/users/userId1) |
| ${request.uriPath} | 요청 경로(예: /users/userId1) |
| ${request.uriPattern} | 요청이 매핑된 URI 패턴(예: /users/{userId}) |
| ${request.scheme} | 요청 스킴(http/https) |
| ${request.httpMethod} | 요청 HTTP 메서드(GET, POST ...) |
| ${request.timestamp} | 요청 시간(Timestamp) |
| ${request.queryString.QUERY_STRING_NAME} | 요청 쿼리 파라미터 |
| ${request.header.HEADER_NAME} | 요청 헤더 |
| ${response.httpStatus} | 응답 HTTP 상태 코드 |
| ${error.resultCode} | 오류 코드 |
| ${error.resultMessage} | 오류 메시지 |
[주의] 경로 변수
선택된 경로와 상위 경로에 선언된 경로 변수만 사용할 수 있습니다.[참고] 컨텍스트 변수의 사용
${CONTEXT_VARIABLE} 또는 $!{CONTEXT_VARIABLE} 형식으로 사용이 가능하며, CONTEXT_VARIABLE에는 정의된 컨텍스트 변수만 사용할 수 있습니다. ${CONTEXT_VARIABLE}로 사용하면, 컨텍스트 변수의 값이 없을 경우 ${CONTEXT_VARIABLE} 문자열이 대체되지 않습니다. $!{CONTEXT_VARIABLE}처럼 $!로 사용하면 컨텍스트 변수의 값이 없을 경우 빈 문자열로 대체됩니다.[참고] queryString, header의 복수 값을 갖는 경우에 백엔드 엔드포인트로의 전달
동일한 이름을 갖는 쿼리 파라미터와 헤더에 대해 복수 개의 값이 존재하는 경우 콤마(,)로 값으로 통합됩니다. 예시: /users?id=user1&id=user2 → /users/id=user1,user2
Cross-Site 방식 내에서 XMLHttpRequest API 호출을 할 수 있게 합니다.
[주의] CORS 플러그인
- CORS 플러그인을 등록하면 선택된 경로의 메서드에 OPTIONS 메서드가 등록됩니다. 하위 경로와 메서드에 덮어쓰기 옵션을 체크한 경우에는 하위 경로에도 등록됩니다. OPTIONS 메서드가 이미 등록되어 있는 경우, CORS에 의해 자동 생성되는 OPTIONS 메서드로 대체됩니다. - CORS 플러그인을 통해 등록된 OPTIONS 메서드는 리소스 트리에서 선택이 불가하며, 수정과 삭제를 할 수 없습니다. - CORS 플러그인을 삭제하면 CORS 플러그인에 의해 자동 생성된 OPTIONS 메서드는 일괄적으로 삭제됩니다.
요청 헤더를 추가하거나 변경합니다.
[참고] 요청 헤더 추가와 변경
- 원본 요청에 없는 헤더는 추가됩니다. - 원본 요청에 있는 헤더는 요청 헤더 변경 플러그인에 설정된 헤더값으로 대체됩니다. - 원본 요청에 있는 헤더의 삭제는 불가합니다.
클라이언트 요청의 헤더에서 지정된 헤더를 삭제한 후 백엔드에 요청합니다.
[참고] 요청 헤더 변경과 삭제 설정
요청 헤더 변경과 요청 헤더 삭제 플러그인을 동시에 설정하였을 경우, 요청 헤더 변경 적용 후 요청 헤더 삭제가 적용됩니다.
응답 헤더 변경 플러그인은 백엔드 응답에 헤더를 추가하거나 변경합니다.
[참고] 응답 헤더 추가와 변경
- 백엔드 엔드포인트의 응답에 없는 헤더는 추가됩니다. - 백엔드 엔드포인트의 응답에 있는 헤더는 요청 헤더 변경 플러그인에 설정된 헤더값으로 대체됩니다.
백엔드 응답 헤더에서 지정된 헤더를 삭제한 후 클라이언트에 응답합니다.
[참고] 응답 헤더 변경과 삭제 설정
응답 헤더 변경과 응답 헤더 삭제 플러그인을 동시에 설정하였을 경우, 응답 헤더 변경 적용 후 응답 헤더 삭제가 적용됩니다.
백엔드 엔드포인트 요청에 쿼리 문자열 파라미터를 추가합니다.
예: 파라미터 이름과 값을 name, value로 설정하면 name=value 쿼리 문자열 파라미터가 백엔드 엔드포인트 요청 시 추가됩니다.
[참고] 요청 쿼리 문자열 파라미터
- '원본 요청의 쿼리 문자열 파라미터'와 같은 키를 갖는 '요청 쿼리 문자열 파라미터'는, '원본 요청의 쿼리 문자열'을 대체하지 않고 추가됩니다. - 쿼리 문자열 파라미터의 값은 인코딩되어 백엔드 엔드포인트로 전달됩니다.
스테이지는 리소스를 배포하는 단계입니다.
[참고] 스테이지
- 스테이지를 생성하려면 리소스 메서드가 하나 이상 등록돼 있어야 합니다. - 스테이지는 API Gateway 서비스당 최대 10개까지 생성 가능합니다. - API Gateway로 수신된 요청을 백엔드 엔드포인트로 전달할 때 기본으로 스테이지에 정의된 백엔드 엔드포인트 URL로 요청을 전달합니다.
[주의] 스테이지 배포
수정된 백엔드 엔드포인트 URL을 API Gateway 서비스에 적용하려면 스테이지를 배포해야 합니다.
[주의] 스테이지 삭제
- 서비스에서 사용 중인 스테이지를 삭제하면 더 이상 API Gateway로 요청이 인입되지 않습니다. - 삭제된 스테이지는 복구가 불가하므로 반드시 서비스에서 사용중인지 확인 후 삭제를 진행하세요. - 스테이지와 연결된 사용량 계획이 존재하면 스테이지를 삭제할 수 없습니다.
리소스를 변경한 후 스테이지에 변경된 리소스를 적용하려면 스테이지 관리화면에서 리소스 가져오기를 진행합니다.
[주의] 리소스 가져오기
- 스테이지에 리소스가 적용된 후에는 기존 리소스로 복구가 불가합니다. - 리소스에 변경된 사항이 없는 경우 리소스 가져오기 버튼이 비활성화됩니다.
스테이지에 설정된 리소스와 설정을 API Gateway 서비스에 적용하려면 스테이지를 배포해야 합니다.
스테이지 배포 이후 배포된 이력들을 확인할 수 있으며, 이전 배포 설정으로 스테이지를 되돌릴 수 있습니다.
[주의] 이전 배포 이력으로 스테이지 되돌리기
- 스테이지 되돌리기를 사용할 경우, 이를 API Gateway 서비스에 적용하려면 스테이지를 배포해야 합니다.
스테이지 배포를 통해 배포된 형상을 API 설명서를 통해 확인 할 수 있습니다. 자세한 내용은 API 설명서를 참고합니다.
IP ACL을 통해 지정된 클라이언트 IP에 대해 API Gateway 요청을 허용/거부할 수 있습니다.
[참고] IP ACL 등록 개수 제한 및 클라이언트 IP 체크
- IP ACL의 IP 접근 대상은 최대 100개까지 입력 가능합니다. - 네트워크 주소 변환(NAT: Network Address Translation)에 의해 클라이언트의 Source IP가 변경된 경우, 변경된 IP를 기준으로 IP ACL을 체크하므로 주의하시기 바랍니다.
HMAC 인증을 사용하면 API Gateway로 수신된 요청이 중간 공격자에 의해 변조되는 것을 방지하며, 요청 유효 시간을 설정하여 Reply Attack 공격을 예방합니다.
[참고] HMAC 인증 실패 응답
HMAC 인증 실패 시 401 Unauthorized 응답이 반환됩니다.[주의] 요청 유효 시간
- 0초로 설정할 경우, 요청 유효 시간을 체크하지 않습니다. 이 경우 Reply Attack 공격에 취약할 수 있습니다. - 유효 시간을 너무 작게 설정하면 API Gateway가 요청을 검증하기 전 유효 시간이 초과되어 요청이 거부될 수 있습니다. 기대하는 요청 유효 시간보다 10초 이상 크게 설정하기를 권장합니다. - API 클라이언트는 시간 동기화 설정 NTP(Network Time Protocol)이 유효한지 반드시 검증하시기 바랍니다. 동기화되지 않은 시간 정보로 인해 요청이 거부될 수 있습니다.[참고] 필수 검증 헤더
필수 검증 헤더를 설정한 경우, API 요청 검증 시 필수 검증 헤더가 요청에 포함되었는지와 signature에도 해당 헤더가 포함된 값인지 검증합니다. 설정 시 필수 검증 헤더가 요청과 singature 생성 시 포함되었는지 확인하시기 바랍니다.
HMAC 인증을 하려면 API 요청 클라이언트는 다음의 인증 헤더와 요청 시간 헤더를 포함하여 요청해야 합니다.
| 헤더 이름 | 헤더값 |
|---|---|
| Authorization | hmac algorithm="<encrypt_algorithm>", headers="<validation_headers>", signature="<base64_digest>" |
| x-nhn-date | ISO8601 형식의 시간 |
[참고] x-nhn-date의 ISO8601 형식
- UTC 표기: yyyy-MM-dd'T'HH:mm:ssZ - UTC 기준 타임 오프셋 표기: yyyy-MM-dd'T'HH:mm:ss±hh:mm
Authorization 또는 x-nhn-date 헤더가 요청에 포함되지 않은 경우 HMAC 인증에 실패합니다.
Authorization 헤더값은 다음과 같이 생성합니다.
| Credential 이름 | 값 |
|---|---|
| algorithm | HmacSHA256 또는 HmacSHA1 |
| headers | HMAC 인증 시 검증할 헤더 목록 콘솔에서 HMAC 필수 검증 헤더에 등록한 헤더는 반드시 포함해야 합니다. |
| signature | SiginToString 문자열을 암호화한 후 Base64 인코딩한 값 |
[HTTP Method]\n
[Request URL]\n
[Request datetime]\n
[header1-name]:[value1]\n
[header2-name]:[value1,value2...]\n
...
GET /members?isEnable=false&type=public HTTP/1.1
Host: http://kr1-example.api.nhncloudservice.com
x-nhn-date: 2021-02-23T00:00:00+09:00
x-nhn-client-id: nhn
x-nhn-client-ip: 10.0.0.1,10.0.0.2
GET
/members?isEnable=false&type=public
2021-02-23T00:00:00+09:00
host:kr1-example.api.nhncloudservice.com
x-nhn-client-id: nhn
x-nhn-client-ip: 10.0.0.1,10.0.0.2
String secretKey = "HMAC에 설정한 비밀키";
// 암호화 알고리즘 HmacSHA1 또는 HmacSHA256
SecretKeySpec signingKey = new SecretKeySpec(secretKey.getBytes(), "HmacSHA256");
Mac mac = Mac.getInstance("HmacSHA256");
mac.init(signingKey);
String message = "StringToSign";
byte[] rawHmac;
rawHmac = mac.doFinal(message.getBytes());
String authorization = new String(Base64.encodeBase64(rawHmac));
Authorization:hmac algorithm="HmacSHA256", headers="host,x-nhn-client-id,x-nhn-client-ip" , signature="V5Dye9kgG3tvZOOZertd5LXE0q8CcJGXCxEFCR71hUE="
x-nhn-date:2021-02-23T00:00:00+09:00
[주의] SignToString 생성 주의 사항
- SignToString 각 필드는 개행 문자(\n)로 구분합니다. - headers에 정의된 헤더는 SignToString 생성 시 포함되어야 합니다. - headers에 정의한 헤더가 없는 경우, [header name]과 [header value]은 SignToString 생성에 포함하지 않습니다. - headers에 정의한 헤더 순서대로 SignToString을 생성해야 합니다. - 예: headers="header1,header2" 라면, SignToString을 생성할 때도 header1, header2 순서대로 헤더를 추가해야 합니다. - SignToString의 헤더 이름은 영소문자(lowercase) 로 통일한 후 생성합니다. - 예: X-NHN-Header → x-nhn-header - 헤더값이 여러 개인 경우, 콤마(,)로 구분하여 헤더값을 작성합니다. - 예: header1-name:header1-value1,header1-value2 - 헤더 이름과 값은 콜론(:)으로 구분하며, 값 구분 시 중간에 공백 문자를 포함하지 않습니다.
JWT 토큰의 서명과 클레임을 검증합니다. 사용자 서비스에서는 토큰을 검증하지 않고 토큰값을 사용할 수 있습니다.
| 헤더 이름 | 헤더값 |
|---|---|
| Authorization | Bearer "<jwt-token>" |
[참고] JWT 토큰 인증 실패 응답
JWT 토큰 인증 실패시 401 Unauthorized 응답이 반환됩니다. 자세한 내용은 Gateway 오류 코드 문서를 참고합니다.[참고] JWT 토큰 생성
API Gateway는 JWT 토큰의 서명과 클레임 조건과 일치하는지만 검증합니다. JWT 토큰 생성은 사용자의 애플리케이션 또는 인증 서비스 제공자를 통해 생성해야 합니다. 개발 및 테스트목적의 JWT 토큰 생성은 JWT 토큰 디버거를 참고합니다.[참고] JWKS(JSON Web Key Set) URI 설명 및 주의사항
JWKS은 API Gateway가 토큰 서명을 검증하기 위해 필요한 JWK(Json Web Key) 암호화 키에 대한 JSON 데이터입니다. JWK에 대한 자세한 내용과 사양은 RFC7515 문서를 참고합니다. 설정된 JWKS URI는 API Gateway가 접근할 수 있도록 공개되어 있어야 하며, 네트워크, 방화벽 등에 의해 차단되지 않도록 합니다. 설정된 JWKS URI는 API Gateway가 항상 접근이 가능하도록 운영되어야 합니다. JWKS URI에 포트를 직접 지정하는 경우 80, 443, 10000~12000 포트만 사용 가능합니다.[주의] JWKS 캐싱
API Gateway는 JWKS URI의 응답을 5분간 캐싱합니다. API Gateway의 캐싱으로 인해 JWKS 변경 사항이 API Gateway에 반영되기까지 최대 5분 이상 소요될 수 있습니다.
API Gateway의 액세스 로그를 Log & Crash Search 서비스에 보관할 수 있는 기능입니다.
액세스 로그는 Log & Crash Search 서비스에서 확인할 수 있습니다.
logType: "NHN Cloud-APIGateway"| 필드 | 설명 |
|---|---|
| longRequestTime | 요청 일시의 타임스탬프 |
| requestPath | 요청 경로 |
| resourcePath | 요청이 매핑된 리소스 경로 |
| requestHttpMethod | 요청 HTTP 메서드 |
| clientIp | 요청 클라이언트 IP |
| responseHttpStatus | 응답 HTTP 상태 코드 |
| body | {clientIp} - [{requestTime}] "{requestHttpMethod} {requestPath}" {responseHttpStatusCode} 형식의 문자열 |
| host | 요청 호스트: 스테이지 URL의 도메인 |
| logType | 로그 타입: "NHN Cloud-APIGateway" 고정 값 |
| logLevel | 로그 레벨: 응답 상태 코드가 400 미만인 경우 "INFO", 400 이상인 경우 "ERROR" |
| errorCode | API Gateway에서 오류가 발생한 경우 게이트웨이 오류 코드, 오류 미발생 시 빈 값 |
| errorMessage | API Gateway에서 오류가 발생한 경우 게이트웨이 오류 메시지, 오류 미발생 시 빈 값 |
[참고] Log & Crash Search 이용 요금 안내
액세스 로그는 Log & Crash Search 서비스에 저장되며, Log & Crash Search 서비스 이용 요금이 별도 청구됩니다. Log & Crash Search 서비스 소개와 이용 요금은 아래 링크를 참고하세요. Log & Crash Search 서비스 소개 바로 가기 Log & Crash Search 이용 요금 바로 가기[주의] 액세스 로그 기능 이용 중 Log & Crash Search 서비스 비활성화 시 유의 사항
액세스 로그 기능 이용 중 Log & Crash Search 서비스를 비활성화하면, 액세스 로그는 더 이상 저장되지 않으며 액세스 로그 기능은 자동으로 비활성화됩니다. 다시 액세스 로그 기능을 이용하려면, Log & Crash Search 서비스를 활성화한 후 액세스 로그 기능을 다시 활성화하시기 바랍니다.
사전 호출 API는 백엔드 엔드포인트를 호출하기 전에 사용자가 지정한 API를 호출하여 호출의 응답 코드에 따라 백엔드 엔드포인트 호출 여부를 결정합니다. API Gateway를 통해 들어온 요청 헤더를 포함하여 사전 호출 API를 호출하고, 사전 호출 API에서는 전달받은 헤더 내용에 따라 응답 코드를 반환합니다.
사전 호출 API의 응답 코드가 200이면 백엔드 엔드포인트를 호출하고, 응답 코드가 200이 아니면 사전 호출 API의 응답 결과를 반환합니다. 만약, 사전 호출 API 호출에 실패하면 오류를 반환합니다.
백엔드 엔드포인트를 호출하기 전에 별도 API 호출을 통한 인증이 필요하거나 먼저 호출되어야하는 API가 존재하는 등의 경우에 활용이 가능합니다.
[참고] 사전 호출 API의 응답 결과 캐싱
사전 호출 API의 응답 결과 코드가 200일 경우에만 응답 결과가 캐싱됩니다. 응답 결과 코드가 200이 아닌 경우, 캐시 유효 시간이 설정되어 있더라도 응답 결과가 캐싱되지 않습니다.
API Gateway로 수신된 요청을 백엔드 엔드포인트로 전달할 때 기본으로 스테이지에 정의된 백엔드 엔드포인트 URL로 요청을 전달합니다. 특정 경로 또는 메서드에 대해 백엔드 엔드포인트 URL을 재정의하려면 백엔드 엔드포인트 URL 재정의를 설정합니다.
요청 수 제한을 통해 API Gateway로 수신되는 요청들의 초당 요청 수를 조절할 수 있으며, 이를 통해 백엔드 엔드포인트를 보호할 수 있습니다.
[참고] 요청 수 제한 응답
초당 요청 수 초과 시 429 Too Many Requests 응답이 반환됩니다.[주의] 요청 제한 키
요청 제한 키를 사용하는 경우, 요청에 지정한 키가 포함되어야 합니다. 예를 들어 요청 제한 키로 헤더를 선택하고, X-NHN-CLOUD 값을 입력했다면, 요청 헤더에는 X-NHN-CLOUD가 포함되어야 합니다.
요청에서 요청 제한 키를 찾을 수 없는 경우, 요청 수 제한이 적용되지 않습니다.[주의] 초당 요청 수 정확도
- 설정된 초당 요청 수와 허용되는 실제 요청 수는 요청이 API Gateway에 수신된 시간, 요청 처리 시간 및 기타 요인에 따라 정확히 일치하지 않을 수 있습니다.
등록된 요청 제한 정책을 스테이지 리소스 경로 또는 메서드에 적용합니다. 자세한 내용은 요청 제한 정책을 참고하세요.
API Gateway에 API 요청 시 지정된 API Key만 요청할 수 있도록 제한합니다.
[참고] API Key 실패 응답
API Key 값이 요청 헤더에 포함되지 않거나 유효하지 않거나 사용량 한도를 초과할 경우 API 요청이 거부됩니다. 자세한 내용은 Gateway 오류 코드 문서를 참고합니다.
| 헤더 이름 | 헤더값 |
|---|---|
| x-nhn-apikey | <primary api key 또는 secondary api key> |
API Gateway 리소스에 설정된 요청 파라미터 설정에 따라 클라이언트 요청의 유효성을 검증합니다. 유효성 검증에 실패한 경우에는 오류 응답을 반환하고 요청을 백엔드 엔드포인트로 전달하지 않습니다.
요청 파라미터에 검증할 요청 파라미터에 대한 정보를 설정합니다. 유효성 검증이 지원되는 파라미터 타입과 검증 방식은 아래 내용을 참고하세요.
쿼리 문자열
헤더
폼 데이터
application/x-www-form-urlencoded인 경우에만 폼 데이터를 검증합니다. 요청 본문
application/json인 경우에만 요청 본문을 검증합니다.콘텐츠 타입
*/*로 설정된 경우에는 콘텐츠 타입을 검증하지 않습니다.스테이지에 리소스 적용을 클릭하여 스테이지에 리소스를 적용합니다.
[주의] 폼 데이터와 요청 본문 설정
폼 데이터와 요청 본문은 동시에 설정할 수 없습니다. 동일 리소스에 Content-Type으로 application/x-www-form-urlencoded와 application/json을 동시에 지원할 수 없으므로 콘텐츠 타입에 따라 리소스를 분리해야 합니다.
모델을 정의하여 요청 파라미터와 응답에서 사용 가능한 본문의 형태를 지정할 수 있습니다.
요청 제한 정책은 요청의 경로 변수 또는 요청 헤더 값에 따라 IP ACL과 요청 수 제한을 설정할 수 있는 기능입니다.
[참고] 요청 제한 정책 생성 개수 제한
요청 제한 정책은 API Gateway 서비스당 최대 10개까지 생성 가능합니다.
요청 제한 정책 이름, 기본 초당 요청 제한 수, 잔여 토큰 수 응답 여부를 수정할 수 있습니다. 요청 제한 키 타입과 요청 제한 키는 수정이 불가합니다.
[참고] 요청 제한 정책 삭제 불가
삭제할 요청 제한 정책이 스테이지에 설정되어 있거나 배포된 스테이지에 포함된 경우 삭제가 불가합니다. 삭제하려면 스테이지에 설정된 요청 제한 정책을 삭제하고 스테이지를 배포한 후 삭제하세요.
요청 제한 정책의 제한 키의 값을 생성합니다. 제한 키 값에 따라 IP ACL과 요청 수 제한을 다르게 설정할 수 있습니다. 1. 요청 제한 키 값을 추가할 요청 제한 정책을 선택합니다. 2. 하단 탭에서 요청 제한 키 값 생성 버튼을 클릭합니다. 3. 요청 제한 키 값의 정보를 입력합니다. - 요청 제한 키 값: 요청 제한 키 값을 입력합니다. 요청 제한 키 값별로 IP ACL과 요청 수 제한을 설정할 수 있습니다. - 초당 요청 수: 요청 제한 키 값에 대한 초당 요청 수 제한값을 입력합니다. - 입력하지 않으면 요청 제한 정책에 설정된 기본 초당 요청 수 값으로 제한됩니다. - IP 접근 제어 타입: - 허용: 지정된 IP만 접근을 허용하고 나머지 IP는 모두 거부합니다. (화이트리스트 방식) - 거부: 지정된 IP만 접근을 거부하고 나머지 IP는 모두 허용합니다. (블랙리스트 방식) - IP 접근 대상: - 단건 입력 또는 대량 입력 방식을 선택하여 IP 목록을 쉽게 등록할 수 있습니다. - IP 접근 대상은 IPv4의 단일 IP 또는 CIDR로 입력할 수 있습니다. - 단일 IP 예시: 10.0.0.1 - CIDR 예시: 10.0.0.1/24 - IP 접근 대상을 하나도 입력하지 않으면 IP ACL 접근 제어가 동작하지 않습니다.
초당 요청 수 제한, IP 접근 제어 타입과 IP 접근 대상을 수정합니다. 요청 제한 키 값은 수정이 불가합니다.
게이트웨이에서 정의된 오류 응답 설정을 사용자가 재정의할 수 있습니다.
[참고] 게이트웨이 응답 적용
변경된 게이트웨이 응답은 스테이지 배포 이후에 배포 시점의 형상으로 적용됩니다.
스테이지 URL를 지정된 HTTP 메서드로 API를 호출합니다.
curl --request GET 'https://kr1-xxxxx-test.api.nhncloudservice.com/example'[주의] 스테이지 배포
API를 호출하려면 배포 성공 상태의 배포된 스테이지가 있어야 합니다.[참고] API 호출이 정상적으로 안 되는 경우
- 404 NotFound HTTP 상태 코드가 응답되는 경우 1. 스테이지를 배포 상태가 배포 성공 상태인지 확인합니다. 2. 요청 메서드와 스테이지 URL 및 경로가 올바른지 확인합니다. 3. 백엔드 엔드포인트 서비스에서 백엔드 엔드포인트 URL 경로에 대한 요청 URL이 존재하는지 확인합니다. - 그 외 오류 코드는 Gateway 오류 코드 문서를 참고합니다.[주의] API 호출 제약 사항
- Gateway 클라이언트에서 API Gateway로 요청 크기 제한은 최대 10MB입니다. 이 값은 조정할 수 없습니다. - API Gateway에서 Gateway 클라이언트로의 응답 크기 제한은 최대 10MB입니다. 이 값은 조정할 수 없습니다. - 요청에 대한 응답 타임아웃은 최대 60초입니다. 백엔드 엔드포인트 서비스에서 응답이 지연되는 경우 타임아웃이 발생할 수 있습니다.[주의] API Gateway 요청 차단 정책
- API Gateway 서비스와 백엔드 엔드포인트 서비스를 보호하는 목적으로 백엔드 엔드포인트 서비스가 응답을 하지 않거나 응답 지연(60초 이상)이 지속적으로 발생하는 경우, 해당 백엔드 엔드포인트 서비스에 대한 요청을 일시적으로 거부합니다. - 백엔드 엔드포인트 서비스의 내부 오류(4xx, 5xx 등)에 의해서는 차단되지 않습니다. - 정상적으로 운영 중인 상태가 아니거나 응답 지연(timeout)이 60초 이상이 지연이 발생하는 백엔드 엔드포인트는 연동하지 않는 것을 권장합니다.
API Gateway에서 배포된 스테이지 URL은 외부(인터넷)에서 접근이 허용됩니다. 외부로 노출하지 않을 API는 API Gateway의 리소스로 등록하지 않도록 합니다. 리소스로 등록된 API에서 제한된 클라이언트만 API 요청을 허용하려면 다음의 설정을 참고하여 추가하시기 바랍니다.
API Gateway 서비스과 연동되는 엔드포인트는 API Gateway 서비스와 통신이 허용되어야 정상적으로 서비스가 가능합니다. 통신이 불가한 경우, API Gateway는 Network Connection 관련 오류 응답을 반환합니다. 엔드포인트에서 API Gateway 서비스의 통신을 허용하려면 다음 내용을 참고합니다.
[참고] 통신이 허용되어야 하는 엔드포인트 - 스테이지의 백엔드 엔드포인트 URL에 설정된 엔드포인트 - (설정된 경우) 스테이지의 커스텀 백엔드 엔드포인트 URL에 설정된 엔드포인트 - (설정된 경우) 사전 호출 API > URL에 설정된 엔드포인트 - (설정된 경우) JWT > JWKS URI에 설정된 엔드포인트 * 자체 보유 중인 인스턴스인 경우 1. API Gateway 서비스가 외부망(인터넷)을 통해 엔드포인트와 통신할 수 있도록 엔드포인트 서버에는 공인 IP가 연결되어 있어야 합니다. 2. 엔드포인트의 방화벽 및 네트워크 ACL 설정에서 API Gateway 서비스의 서버 IP 목록에 대한 인바운드 접근을 허용합니다. * [참고] API Gateway 서비스의 IP 대역 * 211.56.2.64/27 3. 엔드포인트의 애플리케이션 포트는 다음과 같이 제한됩니다. * [참고] 제한된 포트 범위: 80, 443, 10000~12000
API 설명서를 이용하면 API Gateway에 등록된 API의 명세를 웹페이지 문서로 관리할 수 있습니다.
API 설명서를 게시하기 위한 절차를 안내합니다.
[참고] 스테이지 배포와 API 설명서 게시
- API 설명서는 최초 스테이지 배포 이후 게시되며, 최초 게시 유형은 비공개로 설정됩니다. - API 설명서는 스테이지 배포 수행 시 배포되는 형상으로 업데이트됩니다.[주의] 게시된 API 설명서에서 API 호출 테스트 시 CORS 설정
- 게시된 API 설명서 도메인 주소와 호출하는 API의 도메인 주소가 다르기 때문에 API 설명서 내에서 호출을 테스트하고자 하는 경우 CORS 설정이 필요할 수 있습니다. - 예: Access-Control-Allow-Origin: https://kr1-docs-apigw.api.nhncloudservice.com Access-Control-Allow-Method: GET, POST, DELETE, PUT, PATCH, HEAD, OPTIONS Access-Control-Allow-Headers: Authorization, x-nhn-apikey, x-nhn-date
대시보드를 통해 API Gateway 서비스, API Key별 API 통계 지표를 확인할 수 있습니다.
리소스 경로와 HTTP 메서드별로 구분된 상세한 통계 지표를 확인할 수 있습니다.
각 API Key별 호출 수를 일 단위 그래프로 확인할 수 있습니다.
사용량 계획의 스테이지에 연결된 API Key만 스테이지 API를 요청할 수 있도록 제한할 수 있으며, 사용량 제어 설정을 통해 연결된 API Key마다 공통 사용량 제한을 적용할 수 있습니다.
사용량 계획 생성 -> 사용량 계획에 스테이지 연결 -> 사용량 계획이 연결된 스테이지에 API Key 연결 -> 스테이지 설정에서 API Key 활성화[참고] 요청 할당량 한도 재설정
요청 할당량은 매월 1일(월별 기간), 매일(일별 기간) UTC 00:00:00에 재설정됩니다.
[주의] 사용량 계획 요청 제어 설정 수정
사용량 계획에서 초당 요청 수 제한, 요청 할당량을 수정할 경우, 별도 배포 절차 없이 연결된 API에 반영됩니다. 할당량 기간 단위를 '일' 또는 '월'로 수정하면, 연결된 API Key 요청 할당량의 사용량은 유지됩니다. 요청 할당량 한도를 낮추면 사용량이 초과될 수 있습니다. 할당량 기간 단위를 '없음'으로 수정하면 연결된 API Key들의 요청 할당량 사용량은 초기화됩니다.
[참고] 연결된 스테이지가 있는 경우 사용량 계획 삭제 불가
사용량 계획과 연결된 스테이지들을 모두 해제한 후 사용량 계획을 삭제할 수 있습니다.
API Key가 요청 가능한 스테이지들을 정의하기 위해 사용량 계획에 스테이지를 연결합니다.
[참고] 이미 연결된 스테이지
이미 연결된 스테이지는 선택 목록에 노출되지 않습니다.
[참고] 연결된 API Key가 있는 경우 스테이지 해제 불가
사용량 계획에 연결된 스테이지를 해제하기 위해서는 스테이지에 연결된 모든 API Key를 해제해야 합니다.
사용량 계획에 연결된 스테이지의 API를 호출하기 위해서 API Key를 연결합니다.
[참고] 다른 사용량 계획의 동일 스테이지에 연결된 API Key는 선택할 수 있는 목록에 노출되지 않으며, 연결할 수 없습니다.
[참고] 선택한 스테이지가 연결된 다른 사용량 계획으로만 변경할 수 있습니다.
[주의] 사용량 계획 변경 시 API Key 요청 할당량의 사용량 초기화
할당량 기간 단위가 '일' 또는 '월'인 사용량 계획으로 변경하면, 연결된 API Key 요청 할당량의 사용량은 유지됩니다. 요청 할당량 한도가 낮은 사용량 계획으로 변경 시 사용량이 초과될 수 있습니다. 할당량 기간 단위가 '없음'인 사용량 계획으로 변경하면, 연결된 API Key 요청 할당량의 사용량은 초기화됩니다.
[주의] 사용자 정의 Primary/Secondary API Key
사용자 정의 Primary/Secondary API Key는 최소 10자 이상의 영문자와 숫자로 구성된 문자열로 생성합니다. API Gateway 전체 서비스에서 고유해야 합니다. 외부에 노출되지 않도록 주의해야 하며 복잡하게 구성하는 것을 권장합니다.
등록된 API Key를 CSV 형식의 파일로 내보낼 수 있습니다.
[참고] API Key 목록에 조회된 API Key만 파일로 내보냅니다.
CSV 형식의 파일로 API Key를 가져올 수 있습니다.
[참고] API Key 중복시 가져오기 실패
중복된 Primary API Key, Sencondary API Key가 존재하면 모든 API Key 가져오기가 실패합니다. 중복된 API Key를 수정한 뒤 가져오기를 다시 시도하세요.
[주의] API Key 상태 변경
API Key 상태를 INACTIVE로 변경하면 해당 API Key를 사용할 수 없습니다.
[참고] 연결된 사용량 계획, 스테이지가 있는 경우 삭제 불가
연결된 사용량 계획, 스테이지가 있는 경우 API Key를 삭제할 수 없습니다.
API 요청 시 API Key 값으로 사용되는 Primary API Key, Secondary API Key는 각각 재발급할 수 있습니다.
기본 스테이지 도메인은 {Region}-{ServiceId}-{StageName}.api.nhncloudservice.com 형식으로 임의로 발급됩니다.
사용자 지정 도메인으로 임의로 발급된 도메인 대신 사용자가 도메인의 Prefix를 지정하여 {CustomDomainPrefix}.capi.nhncloudservice.com 형식의 도메인을 생성할 수 있습니다.
[주의] 사용자 지정 도메인
사용자 지정 도메인은 최소 2자, 최대 50자의 영소문자, 숫자, -로 구성된 문자열로 생성합니다. API Gateway 전체 서비스에서 고유해야 합니다.
[주의] 사용자 지정 도메인 삭제 불가
스테이지에 연결된 사용자 지정 도메인은 삭제할 수 없습니다. 스테이지에서 사용자 지정 도메인을 연결 해제한 후 삭제하세요.
[주의] 스테이지 연결 해제 시 사용자 지정 도메인으로 API 호출 불가
사용자 지정 도메인의 스테이지 연결 해제를 하면 사용자 지정 도메인으로 더 이상 스테이지 API를 호출할 수 없습니다. 사용자 지정 도메인을 이용하여 API를 호출하는 클라이언트가 없는지 반드시 확인한 후 연결을 해제하세요.
API Gateway가 위치한 리전에 장애가 발생하면 해당 리전의 API Gateway는 정상적으로 운영되지 않을 수 있습니다.
특정 리전 장애의 영향 없이 API Gateway 서비스를 운영하려면 복수 개의 리전에 API Gateway를 이중화로 구성하여 회피할 수 있습니다.
다음은 기존에 운영 중인 한국(판교) 리전과 신규로 한국(평촌) 리전에 API Gateway를 구성하여 리전을 이중화하는 시나리오입니다.
[참고] 리소스 > 리소스 가져오기 시 스테이지 플러그인 설정 Swagger 파일로 리소스를 가져올 때 스테이지에 설정된 플러그인은 가져오지 않습니다. 필요한 플러그인은 스테이지 설정에서 별도로 추가하세요.
이 가이드는 NHN Cloud DNS Plus 서비스의 GSLB를 이용합니다. GSLB 설정에 대한 자세한 내용은 DNS Plus 콘솔 사용 가이드를 참고하세요.
서비스 게이트웨이를 이용하면 NHN Cloud 내부에서 클라이언트와 API Gateway가 통신할 때 외부 인터넷을 경유하지 않고, 내부 네트워크로 통신할 수 있습니다. API Gateway 서비스 게이트웨이를 연동하는 방법은 다음 가이드를 참고하세요.
[참고] /etc/hosts 파일 수정
/etc/hosts 파일을 수정하지 않으면 스테이지 URL로 API 호출이 불가합니다. 하나의 서비스 게이트웨이 IP로 여러 개의 API Gateway 스테이지 도메인을 등록하여 사용할 수 있습니다.