Product 생성하기
API Gateway를 사용하려면 먼저 상품을 생성해야 합니다.
① API Gateway > My Products 메뉴를 선택합니다.
② Product 생성을 클릭합니다.
① 상품 생성에 필요한 값을 입력합니다.
- 이름: 상품의 이름을 입력합니다.
- 설명: 상품의 설명을 입력합니다.
- 구독 방식: 구독 방식에는 두 가지가 있습니다.
- 공개 - 자율 구독: 상품의 API를 누구나 사용할 수 있습니다.
- 보호 - 승인 필요: 상품의 API를 사용하기 위해서는 게시자의 승인이 필요합니다.
② Product 생성을 클릭합니다.
① 생성된 상품을 조회할 수 있습니다.
API 생성하기
생성한 상품에 API를 생성합니다. 상품에는 여러 개의 API를 생성할 수 있습니다.
① Product의 APIs 아이콘을 클릭합니다.
① API 생성 화면으로 이동후 새로운 API를 선택합니다.
② API 생성에 필요한 값을 입력합니다.
- API 이름: API의 이름을 입력합니다. API의 이름은 API Gateway의 호출 URL의 경로에 포함됩니다.
- 설명: API에 대한 설명을 입력합니다.
③ API 생성을 클릭합니다.
Resource 생성하기
API가 생성되면 기본으로 Root Resource(/)가 추가됩니다.
Root 하위로 /pets 리소스를 생성합니다.
① 리소스 생성을 클릭합니다.
② Resource 생성에 필요한 값을 입력합니다.
- Resource Path: API URL 경로로 사용할 값을 입력합니다.
괄호를 사용하여 리소스를 경로 변수로 지정할 수 있습니다.
예를 들어 {variable}로 정의된 리소스 경로는 현재 경로를 변수로 사용합니다.
또한 {variable+}로 정의된 리소스 경로는 하위 리소스를 포함한 경로를 변수로 사용합니다.
경로 변수는 엔드포인트의 경로에 파라미터로 사용할 수 있습니다. - CORS 활성화: CORS(Cross-Origin Resource Sharing)를 활성화하기 위해 추가 설정값을 입력합니다.
CORS를 활성화하면, API Gateway에서 CORS 요청을 처리하기 위해 OPTIONS 메서드를 생성합니다.
③ 생성을 클릭합니다.
메서드 생성하기
/pets Resource에 GET 메서드(Method)를 추가합니다.
① 메서드 생성을 클릭합니다.
② 생성할 메서드(Method)를 선택합니다.
엔드포인트 지정하기
HTTP
서비스할 백엔드 서버의 설정을 입력합니다.
① 메서드의 설명을 입력합니다. Swagger 문서를 만들 때 사용됩니다.
② HTTP를 선택합니다.
③ HTTP를 설정하기 위한 값을 입력합니다.
- Stream: 요청의 성격이 파일 업로드라면 이 설정을 켭니다.
- Stream을 껐을 경우 최대 요청 크기는 10MB로 제한됩니다.
- Stream을 켰을 경우 최대 요청 크기는 100MB로 제한됩니다.
- Method: 백엔드 서버로 요청할 Method를 선택합니다.
- URL 경로: 백엔드 서버로 요청할 도메인을 제외한 URL을 입력합니다.
엔드포인트로 호출할 URL 경로를 정의합니다.
리소스 경로 변수 및 요청 파라메터에서 정의한 쿼리 스트링과 헤더를 파라미터로 사용할 수 있습니다.
파라미터는 괄호를 사용하여 정의합니다.
④ API Key 필요, 인증과 유효성 검사를 선택합니다.
- API Key 필요: API Key를 사용할지 선택합니다.
- API Key를 사용하지 않는 경우 Product 구독 방식과 Usage Plan의 적용을 받지 않습니다.
- 인증: 인증 방법을 선택합니다.
- NONE: 인증을 하지 않습니다.
- IAM: 네이버 클라우드 플랫폼에서 제공하는 IAM 인증을 사용합니다.
- 유효성 검사: 유효성 검사 범위를 선택합니다.
- NONE: 유효성 검사를 하지 않습니다.
- Query String & Headers: 쿼리 스트링과 헤더에 대한 유효성 검사를 합니다. 유효성 검사는 Parameters 탭에서 정의한 API 명세를 참고합니다.
⑤ 저장을 클릭합니다.
MOCK
API 호출 결과로 항상 설정한 값을 반환합니다.
① MOCK을 선택합니다.
② MOCK을 설정하기 위한 값을 입력합니다.
- Status Code: 요청에 대한 응답 코드를 설정합니다.
- Response: 요청에 대한 body를 입력합니다.
③ 저장을 클릭합니다.
네이버 클라우드 플랫폼 Service
네이버 클라우드 플랫폼에서 제공되는 서비스를 이용합니다.
① Naver Cloud Platform Service을 선택합니다.
② 엔드포인트로 등록하고자 하는 서비스와 리전 그리고 액션을 선택합니다.
③ 저장을 클릭합니다.
API 명세 정의하기
API 명세를 정의합니다. API 명세는 Swagger UI를 생성하는 데 사용됩니다.
① 요청에 대한 명세를 정의합니다.
- 쿼리 스트링과 헤더는 엔드포인트로 호출할 URL 경로를 정의할 때 리소스 경로 변수처럼 변수로 사용할 수 있습니다.
- 쿼리 스트링: 요청의 쿼리 스트링을 정의합니다. 필수여부를 예로 지정하면 유효성 검사의 대상에 포함됩니다.
Array 타입인 경우 중복된 이름으로 여러 개의 쿼리 스트링을 생성합니다. - 헤더: 요청의 헤더를 정의합니다. 필수여부를 예로 지정하면 유효성 검사의 대상에 포함됩니다.
- 폼 데이터: 요청의 폼 데이터를 정의합니다. 폼 데이터는 유효성 검사에 포함되지 않습니다.
Array 타입인 경우 중복된 이름으로 여러 개의 폼 데이터를 생성합니다.
- 바디: 요청의 바디를 정의합니다. 바디의 모델은 상단 탭의 Models에 정의된 모델을 사용합니다.
- 콘텐츠 타입: 요청의 콘텐츠 타입을 지정합니다.
application/x-www-form-urlencoded, multipart/form-data는 정의된 폼 데이터를 이용하여 요청의 바디를 생성합니다.
그외 콘텐츠 타입은 바디를 이용합니다.
② 응답에 대한 명세를 정의합니다.
- 응답코드: 응답코드를 정의합니다.
- 응답코드를 선택하면 상세 명세를 정의할 수 있습니다.
- 콘텐츠 타입: 응답의 콘텐츠 타입을 지정합니다.
게이트웨이 응답 정의하기
미리 정의된 게이트웨이 응답을 수정할 수 있습니다.
① Gateway Responses 탭으로 이동합니다.
② 게이트웨이에 정의된 응답 유형에 대한 응답 코드를 수정합니다.
③ 응답 헤더를 정의합니다.
④ 콘텐츠 타입별 응답 메시지를 수정합니다.
콘텐츠 변수
응답 헤더와 응답 메시지에는 콘텐츠 변수를 사용할 수 있습니다.
콘텐츠 변수 | 설명 |
---|---|
${context.productName} | Product 이름 |
${context.apiName} | API 이름 |
${context.httpMethod} | 메서드 |
${context.error.message} | 에러 메시지 문자열 |
${context.error.messageString} | 에러 메시지 문자열, "$context.error.message" |
${context.error.responseType} | 응답 유형 |
${context.identity.accountId} | AccessKey의 계정ID (IAM 인증을 사용한 경우) |
${context.identity.apiKey} | API Key (API Key를 사용하는 경우) |
${context.identity.sourceIp} | 호출자 IP |
${context.identity.user} | ${context.identity.accountId}와 동일 |
${context.identity.userAgent} | User Agent |
${context.path} | URL 경로 |
${context.protocol} | 호출 프로토콜, 예시) HTTP/1.1 |
${context.requestId} | 요청 ID |
${context.requestTime} | 1970년 1월 1일 00:00:00 협정 세계시(UTC)부터의 경과 시간을 밀리초(millisecond)로 나타낸 숫자 |
${context.resourcePath} | 리소스 경로 |
${context.methodCode} | 엔드포인트의 메서드 |
${context.methodName} | 엔드포인트의 메서드 |
${context.status} | 응답코드 |
${context.stage} | Stage 이름 |
${method.request.path.PARAM_NAME } |
요청의 경로 변수 |
${method.request.queryString.PARAM_NAME } |
요청의 쿼리 스트링 |
${method.request.header.PARAM_NAME } |
요청의 헤더 |
모델 정의하기
API 명세에서 사용하기 위한 모델을 정의합니다.
① Models 탭으로 이동합니다.
② 추가를 클릭합니다.
① 모델을 정의합니다.
Schema
- 모델을 선언할 때는 JSON schema를 사용합니다.
- 예제
{ "title": "Person", "type": "object", "properties": { "firstName": { "type": "string" }, "lastName": { "type": "string" }, "age": { "description": "Age in years", "type": "integer", "minimum": 0 } }, "required": ["firstName", "lastName"] }
API 테스트
등록한 API를 배포하기 전에 제대로 동작하는지 테스트할 수 있습니다.
테스트에는 인증 및 사용 계획은 적용되지 않습니다.
① 테스트할 도메인을 설정합니다.
② 앞서 정의한 요청 파라미터들을 설정합니다.
③ Test를 클릭하면 하단에 테스트 결과를 볼 수 있습니다.