자습서: 예제를 가져와 REST API 생성 - 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에 액세스할 수 있도록 다음 메서드를 지원합니다.

참고

이 튜토리얼에서는 HTTP 엔드포인트를 예로 사용합니다. 자체 API를 생성할 때는 HTTP 통합에 HTTPS 엔드포인트를 사용하는 것이 좋습니다.

  • 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는 OPTIONS 통합 유형의 MOCK 메서드를 통해 CORS 액세스를 지원합니다. API Gateway는 CORS 액세스를 지원하는 필수 헤더를 반환합니다.

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

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

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

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

    • 첫 번째 API를 생성하려면 REST API에서 빌드를 선택합니다.

    • 이전에 API를 생성한 경우 API 생성을 선택한 다음 REST API에서 빌드를 선택합니다.

  3. REST API 생성에서 예제 API를 선택한 다음 API 생성을 선택하여 예제 API를 생성합니다.

    API Gateway 콘솔의 예시 REST API입니다.

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

  4. 기본 탐색 창에서 리소스를 선택합니다. 새로 생성한 API는 다음과 같이 표시됩니다.

    API Gateway 콘솔로 가져온 후의 예시 API입니다.

    리소스 창은 생성된 API의 구조를 노드 트리 형태로 보여 줍니다. 각 리소스에 정의된 API 메서드가 트리의 엣지입니다. 리소스를 선택하면 모든 메서드가 우측의 방법 테이블에 나열됩니다. 각 메서드와 함께 메서드 유형, 통합 유형, 권한 부여 유형 및 API 키 요구 사항이 표시됩니다.

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

    API Gateway 콘솔의 예시 API에 대한 POST/pets 메서드입니다.

    결과로 나타나는 메서드 실행 창은 선택된 (POST /pets) 메서드의 구조 및 동작에 대한 논리적인 뷰를 보여줍니다.

    메서드 요청 및 메서드 응답은 API와 프런트엔드 간의 인터페이스를 나타내며, 통합 요청 및 통합 응답은 API와 백엔드 간의 인터페이스를 나타냅니다.

    클라이언트는 API를 사용하여 메서드 요청을 통해 백엔드 기능에 액세스합니다. 필요할 경우 수신되는 요청을 백엔드에 전달하기 전에 API Gateway가 통합 요청에서 클라이언트 요청을 백엔드가 수용할 수 있는 형태로 변환합니다. 변환된 요청을 통합 요청이라고 합니다. 마찬가지로 백엔드는 통합 응답에서 응답을 API Gateway로 반환합니다. 그런 다음 API Gateway가 메서드 응답을 라우팅한 후에 클라이언트로 전송합니다. 필요한 경우 API Gateway는 백엔드 응답 데이터를 클라이언트가 기대하는 형태로 변환할 수 있습니다.

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

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

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

  6. 테스트 탭을 선택합니다. 탭을 표시하려면 오른쪽 화살표 버튼을 선택해야 할 수도 있습니다.

  7. 예를 들어, POST /pets 메서드를 테스트하려면 다음의 {"type": "dog","price": 249.99} 페이로드를 요청 본문에 입력한 후 테스트를 선택합니다.

    API Gateway 콘솔에서 POST 메서드를 테스트합니다.

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

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

    API Gateway 콘솔에서 POST 메서드를 테스트한 결과입니다.

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

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

  9. 샘플 API를 배포하려면 API 배포를 선택합니다.

    API 호출자가 API를 간접적으로 호출할 수 있도록 배포 버튼을 사용하여 API를 배포합니다.

  10. 스테이지에서 새 스테이지를 선택한 다음 test를 입력합니다.

  11. (선택 사항) 설명에 설명을 입력합니다.

  12. [배포]를 선택합니다.

  13. 그 결과 표시되는 스테이지 창의 스테이지 세부 정보 아래 URL 호출에 API의 GET / 메서드 요청을 호출하는 URL이 표시됩니다.

    REST API를 생성하면 콘솔에 API의 호출 URL이 표시됩니다.

  14. 복사 아이콘을 선택해 API의 호출 URL을 복사하여 웹 브라우저에 입력합니다. 올바른 응답은 통합 응답에서 매핑 템플릿에 의해 생성된 결과를 반환합니다.

  15. 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 비 프록시 통합을 통해 REST API 생성을 참조하십시오.