[AWS] Amazon API Gateway Developer Portal 구성 방법

Amazon API Gateway에서 Developer Portal(Portals) 기능이 정식으로 제공되면서, 이제 별도의 웹사이트를 구축하거나 샘플 오픈소스 포털을 수정할 필요 없이 AWS 네이티브 환경 안에서 완전 관리형 API 포털을 빠르게 만들 수 있게 되었습니다.
조직 내부 개발자용 포털부터 외부 파트너에게 API를 제공하는 포털까지 폭넓게 구성할 수 있으며, API 검색, 카탈로그화, 문서화, 권한 관리 등이 모두 기본으로 제공됩니다.

준비 사항

Portal 기능은 API Gateway에서 바로 생성할 수 있으며, 포털 인증 기능은 Amazon Cognito 또는 IAM 기반으로 설정할 수 있습니다.
사전 준비는 다음 두 가지입니다.

• 문서화할 REST API 또는 HTTP API 준비
• 포털을 공개할 대상(조직 내부/계열사/파트너)에 맞는 인증 방식 선택

---

1. Developer Portal 생성

콘솔에서 Portal을 생성하는 과정은 매우 간단합니다.

1. AWS Console → API Gateway 이동
2. 좌측 메뉴에서 Portals 선택
3. Create Portal 클릭
4. 포털 이름 입력
5. 인증 방식 선택
   • Public
   • Amazon Cognito 기반 인증(SSO, MFA 포함)
6. 생성 요청 실행

생성 과정에서는 백엔드에 필요한 정적 웹 호스팅(S3), CloudFront, Lambda, API Gateway 구성이 자동으로 이루어지며, 별도의 인프라 작업이 필요하지 않습니다.

포털을 생성하면 고유한 Portal URL이 발급되며, 바로 접속해 기본 템플릿을 확인할 수 있습니다.

2. API 자동 검색 & 문서화 활성화

Portal 기능의 가장 큰 장점 중 하나는 자동 API 검색 및 자동 문서 생성입니다.
특히 여러 계정에서 운영 중인 API를 한 곳에서 문서화할 수 있다는 점이 특징입니다.

1. Portal 상세 페이지로 이동
2. API Sources 메뉴에서 연결할 AWS 계정 선택
3. API Gateway에 배포된 API 목록이 자동으로 수집됨
4. API별 노출 여부를 설정
5. API 이름·카테고리·설명 등을 포털용으로 수정 가능

API가 업데이트되면 포털의 문서도 자동으로 최신 버전으로 바뀌므로, 운영자가 추가로 관리할 필요가 없습니다.

3. API Product 구성하기

여러 API를 단일 제품처럼 묶는 기능을 제공해, 조직 단위로 API 공개 범위를 제어할 수 있습니다.

예를 들어,

• ERP 관련 API 묶음
• 주문 기반 API 세트
• 모바일 앱 전용 API 묶음

이런 식으로 여러 API를 ‘제품(Product)’ 단위로 구성할 수 있습니다.

구성 절차:

1. Portal → Products 메뉴로 이동
2. Create Product 선택
3. 포함할 API 선택
4. 외부 노출 여부 또는 특정 조직·파트너 전용으로 제한
5. API 경로 중 공개하고 싶은 메서드만 선택적 노출

이 기능은 대규모 조직에서 API 카탈로그 구조를 유지하는 데 특히 유용합니다.

4. 포털 브랜딩 설정

Portal은 기본 템플릿이 제공되며, 최소한의 UI 커스터마이징도 지원합니다.

설정 가능 항목:

• 로고 이미지
• 브랜드 컬러
• 회사명·태그라인
• 추가 문서/가이드 업로드

관리 화면에서 브랜딩을 변경하면 CloudFront 배포가 자동 진행되며, 별도의 빌드 과정 없이 즉시 적용됩니다.

5. 인증 및 접근 제어 구성

Portal은 크게 두 가지 방식으로 접근 제어를 구성할 수 있습니다.

5.1. Cognito 기반 인증

• 회사 SSO(SAML/OIDC) 연동
• MFA 적용
• 사용자 그룹별 API 접근 권한 분리

절차는 다음과 같습니다.

1. Cognito User Pool 생성
2. 포털 설정에서 User Pool 선택
3. 승인된 사용자 그룹을 제품(Product)에 매핑

5.2. Public 접근(읽기 전용)

• 공개 문서 사이트 형태로 운영 가능
• Try It 사용 시 API 자체 Authorizer 또는 IAM 권한이 그대로 적용됨

필요한 경우 API 수준에서 IAM, Lambda Authorizer, JWT Authorizer 등을 그대로 유지할 수 있으며, Portal이 이를 대체하거나 우회하지 않습니다.

6. Try It 기능 활성화

Portal에서 제공하는 Try It 기능은 개발자가 브라우저에서 직접 API를 호출해 볼 수 있도록 지원합니다.

활성화 절차는 간단합니다.

1. 각 API의 Authorization 설정이 포털에서 사용 가능한지 확인
2. 필요 시 API Key 또는 Cognito 인증 기반으로 테스트
3. Request/Response가 포털 내 콘솔 UI로 표시됨

이 기능은 온보딩 속도를 크게 줄여줍니다.

7. 사용 분석 및 운영 지표 확인

Portal은 CloudWatch RUM과 CloudTrail과의 통합을 통해 운영 지표를 제공합니다.

확인할 수 있는 주요 지표는 다음과 같습니다.

• 포털 방문자 분석
• 검색 키워드 및 API 문서 열람 경로
• 특정 API의 호출 테스트 행동 분석
• 계정 간 공유된 제품(Product)의 사용량 추적

추가로 AWS Resource Access Manager(RAM)을 통해 다른 계정 및 조직 OU 단위로 Portal을 공유할 수 있어, 멀티 계정 구조에서도 쉽게 확장할 수 있습니다.

---

구성 예시: 사내 개발자 포털 구축

1. Portal 생성 후 Cognito SSO 연동
2. 개발팀·운영팀·데이터팀별 그룹 생성
3. 각 팀에 필요한 API를 Product로 묶어서 제공
4. Try It 기능으로 API 테스트 제공
5. RUM 기반으로 API 검색 패턴 분석
6. API Gateway 배포만으로 문서 자동 업데이트

이 구조를 사용하면 별도의 문서 사이트를 유지할 필요 없이 API 변경 내용이 즉시 포털에 반영됩니다.

정리

Portal 기능은 API 운영 조직에게 상당히 실용적인 기능이며, 기존 Developer Portal을 직접 구축해 유지하던 비용과 시간을 크게 절약할 수 있습니다.