Amazon API Gateway
개발자 안내서

자습서: 예제를 가져와 REST API 생성

Amazon API Gateway 콘솔을 사용하여 PetStore 웹 사이트에 대한 HTTP 통합으로 간단한 REST API를 생성 및 테스트할 수 있습니다. API 정의는 OpenAPI 2.0 파일로 미리 구성되어 있습니다. API 정의를 API Gateway로 로드한 후 API Gateway 콘솔을 사용하여 API의 기본 구조를 검사하거나 API를 간단히 배포 및 테스트할 수 있습니다.

PetStore 예제 API는 클라이언트가 HTTP 백엔드 웹 사이트 http://petstore-demo-endpoint.execute-api.com/petstore/pets에 액세스할 수 있도록 다음 메서드를 지원합니다.

  • GET /: 백엔드 엔드포인트와 통합되지 않은 API의 루트 리소스에 대한 읽기 액세스용입니다. API Gateway는 PetStore 웹 사이트의 개요로 응답합니다. 이는 MOCK 통합 유형의 예제입니다.

  • GET /pets: 비슷한 이름의 백엔드 /pets 리소스와 통합된 API의 /pets 리소스에 대한 읽기 액세스용입니다. 백엔드는 PetStore에서 사용 가능한 반려 동물의 페이지를 반환합니다. 이는 HTTP 통합 유형의 예제입니다. 통합 엔드포인트의 URL은 http://petstore-demo-endpoint.execute-api.com/petstore/pets입니다.

  • POST /pets: 백엔드 /pets 리소스와 통합된 API의 /petstore/pets 리소스에 대한 쓰기 액세스용입니다. 올바른 요청을 수신하면 백엔드는 지정된 반려 동물을 PetStore에 추가하고 결과를 호출자에게 반환합니다. 통합은 HTTP이기도 합니다.

  • GET /pets/{petId}: 수신되는 요청 URL의 경로 변수로 지정된 petId 값으로 식별되는 반려 동물에 대한 읽기 액세스용입니다. 이 메서드에는 HTTP 통합 유형도 있습니다. 백엔드는 PetStore에 있는 지정된 반려 동물을 반환합니다. 백엔드 HTTP 엔드포인트의 URL은 http://petstore-demo-endpoint.execute-api.com/petstore/pets/n이며 여기서 n은 쿼리된 반려 동물의 식별자로서 정수입니다.

API는 MOCK 통합 유형의 OPTIONS 메서드를 통해 CORS 액세스를 지원합니다. API Gateway는 CORS 액세스를 지원하는 필수 헤더를 반환합니다.

다음 절차에서는 API Gateway 콘솔을 사용하여 예제 API를 생성하고 테스트하는 단계를 안내합니다.

예제 API를 가져와서 구축 및 테스트하려면

  1. 아직 하지 않았다면, 사전 조건: API Gateway에서 API 구축 준비의 단계를 완료합니다.

  2. https://console.aws.amazon.com/apigateway에서 API Gateway 콘솔에 로그인합니다.

  3. 다음 중 하나를 수행하십시오.

    1. 계정에서 API를 처음 사용하는 경우 API Gateway 콘솔 시작 페이지에서 시작하기를 선택합니다.

      힌트가 포함된 메시지가 나타나면 확인을 선택하여 닫고 계속 진행합니다.

    2. API를 처음 사용하지 않는 경우 API Gateway APIs(API) 홈 페이지에서 Create API(API 생성)를 선택합니다.

  4. Create new API(새 API 생성)에서 예제 API(Example API)를 선택한 다음 가져오기를 선택하여 예제 API를 생성합니다. API를 처음 사용하는 경우 API Gateway 콘솔에서 기본 옵션으로 시작합니다.

    가져오기를 선택하기 전에 OpenAPI 정의를 아래로 스크롤하여 이 예제 API의 세부 정보를 확인할 수 있습니다.

  5. 새로 생성한 API는 다음과 같이 표시됩니다.

    리소스 창은 생성된 API의 구조를 노드 트리 형태로 보여 줍니다. 각 리소스에 정의된 API 메서드가 트리의 엣지입니다. 리소스를 선택하면 모든 메서드가 우측의 방법 창에 나열됩니다. 각 메서드 아래에는 엔드포인트 URL, 권한 부여 유형 및 API 키 요건을 포함한 메서드의 요약 정보가 표시됩니다.

  6. 메서드의 세부 정보를 보거나 메서드 설정을 수정하거나 메서드 호출을 테스트하려면, 메서드 목록이나 리소스 트리에서 메서드 이름을 선택합니다. 여기에서는 그림과 같이 POST /pets 메서드를 선택합니다.

    결과로 나타난 메서드 실행(Method Execution) 창은 선택된 (POST /pets) 메서드의 구조 및 동작에 대한 논리적 뷰를 보여줍니다. 메서드 요청(Method Request)메서드 응답(Method Response)은 API와 API 프런트엔드(클라이언트) 간의 인터페이스이고, 통합 요청(Integration Request)통합 응답(Integration Response)은 API와 백엔드(http://petstore-demo-endpoint.execute-api.com/petstore/pets) 간의 인터페이스입니다. 클라이언트는 API를 사용하여 Method Request(메서드 요청)를 통해 백엔드 기능에 액세스합니다. 필요할 경우 수신되는 요청을 백엔드에 전달하기 전에 API Gateway가 Integration Request(통합 요청)에서 클라이언트 요청을 백엔드가 수용할 수 있는 형태로 변환합니다. 변환된 요청을 통합 요청이라고 합니다. 마찬가지로 백엔드는 Integration Response(통합 응답)에서 응답을 API Gateway로 반환합니다. 그런 다음 API Gateway가 Method Response(메서드 응답)를 라우팅한 후에 클라이언트로 전송합니다. 다시 말씀드리지만, 필요할 경우 API Gateway가 백엔드 응답 데이터를 클라이언트가 기대하는 형태로 변환할 수 있습니다.

    API 리소스에서의 POST 메서드의 경우, 메서드 요청의 페이로드가 통합 요청의 페이로드와 같은 형식인 경우 메서드 요청 페이로드를 수정 없이 통합 요청에 전달할 수 있습니다.

    GET / 메서드 요청은 MOCK 통합 유형을 사용하며 실제 백엔드 엔드포인트에 연동되지 않습니다. 해당 통합 요청(Integration Response)을 설정하여 정적인 HTML 페이지를 반환합니다. 메서드가 호출되면 API Gateway가 요청을 단순히 수용하고 구성된 통합 요청을 Method Response(메서드 응답) 방식으로 클라이언트에 즉시 반환합니다. 모의 통합을 사용하여 백엔드 엔드포인트를 요구하지 않고 API를 테스트할 수 있습니다. 응답 본문 매핑 템플릿에서 생성된 로컬 응답도 모의 통합을 사용하여 제공할 수 있습니다.

    API 개발자는 메서드 요청 및 메서드 응답을 구성하여 API의 프런트엔드 상호 작용의 동작을 제어합니다. API의 백엔드 상호 작용 동작은 통합 요청 및 통합 응답을 설정하여 제어합니다. 여기에는 메서드와 해당 통합 간의 데이터 매핑 작업이 수반됩니다. 메서드 설정은 자습서: HTTP 비 프록시 통합을 사용하여 API 빌드에서 다룹니다. 지금은 API의 종단 간 사용자 경험을 테스트하는 데 중점을 두겠습니다.

  7. 클라이언트(Client)에서 테스트를 선택하여(앞의 이미지에 나와 있는 바와 같이) 테스트를 시작합니다. 예를 들어, POST /pets 메서드를 테스트하려면 다음의 {"type": "dog","price": 249.99} 페이로드를 요청 본문(Request Body)에 입력한 후 테스트 버튼을 클릭합니다.

    이 입력은 PetStore 웹 사이트 상의 반려 동물 목록에 추가하려는 반려 동물의 속성을 지정합니다.

  8. 결과는 다음과 같습니다.

    출력의 로그 항목은 메서드 요청에서 통합 요청으로, 그리고 통합 응답에서 메서드 응답으로의 상태 변화를 나타냅니다. 이는 요청 실패를 야기하는 매핑 오류 문제를 해결하는 데 유용할 수 있습니다. 이 예제에서는 어떤 매핑도 적용되지 않습니다. 즉, 메서드 요청 페이로드가 통합 요청을 통해 백엔드로 전달되고, 마찬가지로 백엔드 응답은 통합 응답을 통해 메서드 응답으로 전달됩니다.

    API Gateway의 테스트-호출-요청 기능 이외의 클라이언트를 사용하여 API를 테스트하려면 우선 API를 단계에 배포해야 합니다.

  9. 샘플 API를 배포하려면 PetStore API를 선택한 후 작업 메뉴에서 API 배포를 선택합니다.

    API 배포배포 단계에서 [New Stage]를 선택합니다. 왜냐하면 이것이 API의 첫 배포이기 때문입니다. Stage name(단계 이름)에서 이름(예: test)을 입력하고, 선택적으로 Stage description(단계 설명)Deployment description(배포 설명)에 설명을 입력합니다. 배포를 선택합니다.

    그 결과 표시되는 단계 편집기(Stage Editor) 창의 URL 호출(Invoke URL)에 API의 GET / 메서드 요청을 호출하는 URL이 표시됩니다.

  10. 단계 편집기(Stage Editor)에서 URL 호출(Invoke URL) 링크를 따라가 브라우저에서 GET / 메서드 요청을 제출합니다. 올바른 응답은 통합 응답에서 매핑 템플릿에 의해 생성된 결과를 반환합니다.

  11. Stages(단계) 탐색 창에서 테스트 단계를 확장하고 /pets/{petId}에 대한 GET을 선택한 다음, https://api-id.execute-api.region.amazonaws.com/test/pets/{petId}Invoke URL(URL 호출){petId} 값을 복사합니다. 은 경로 변수입니다.

    URL 호출(Invoke URL) 값(이전 단계에서 복사한 값)을 브라우저의 주소 표시줄에 붙여 넣어 {petId}1(예)로 대체한 다음 엔터 키를 눌러 요청을 제출합니다. 200 OK 응답이 다음의 JSON 페이로드와 함께 반환되어야 합니다.

    { "id": 1, "type": "dog", "price": 249.99 }

    그림에서와 같이 API 메서드 호출이 가능한데, 권한 부여(Authorization) 유형이 NONE으로 설정되어 있기 때문입니다. AWS_IAM 권한 부여가 사용되었다면 서명 버전 4 (SigV4) 프로토콜을 사용하여 요청에 서명해야 합니다. 이러한 요청의 예는 자습서: HTTP 비 프록시 통합을 사용하여 API 빌드을 참조하십시오.