AWS API Gateway REST API 완벽 가이드

AWS API Gateway로 REST API를 만들고 배포하는 전 과정을 다룹니다. 초급 개발자도 쉽게 따라할 수 있도록 실무 상황을 스토리로 풀어냈습니다. API Gateway의 핵심 개념부터 실제 배포까지 단계별로 학습합니다.

1. API Gateway란?

이제 막 백엔드 개발을 시작한 김개발 씨가 선배에게 질문했습니다. "Lambda 함수는 만들었는데, 이걸 어떻게 외부에서 호출하나요?" 선배 박시니어 씨가 웃으며 대답했습니다.

"바로 그럴 때 API Gateway가 필요하지."

API Gateway는 AWS의 관리형 서비스로, REST API를 쉽게 생성하고 관리할 수 있게 해줍니다. 마치 건물의 정문 경비원처럼, 외부 요청을 받아서 적절한 Lambda 함수나 백엔드 서비스로 연결해주는 역할을 합니다.

인증, 모니터링, 트래픽 관리까지 자동으로 처리해주기 때문에 개발자는 비즈니스 로직에만 집중할 수 있습니다.

다음 코드를 살펴봅시다.

// API Gateway를 통해 Lambda 함수 호출하는 예제
const AWS = require('aws-sdk');
const apigateway = new AWS.APIGateway();

// REST API 생성
const params = {
  name: 'MyFirstAPI',
  description: '첫 번째 REST API 생성',
  endpointConfiguration: {
    types: ['REGIONAL'] // 리전별 엔드포인트
  }
};

apigateway.createRestApi(params, (err, data) => {
  if (err) console.log(err);
  else console.log('API ID:', data.id); // API ID 출력
});

김개발 씨는 입사 2개월 차 주니어 개발자입니다. Lambda 함수로 간단한 사용자 조회 기능을 만들었지만, 막상 프론트엔드 팀에게 어떻게 전달해야 할지 막막했습니다.

"이 Lambda 함수를 어떻게 호출하라고 하지?" 박시니어 씨가 옆자리에서 화면을 살짝 보더니 말했습니다. "아, Lambda 함수만 있고 API Gateway가 없네요.

그럼 외부에서 접근할 수가 없어요." 그렇다면 API Gateway란 정확히 무엇일까요? 쉽게 비유하자면, API Gateway는 마치 대형 건물의 정문 경비실과 같습니다.

방문객이 건물에 들어오려면 반드시 정문을 거쳐야 하고, 경비원이 신분을 확인한 뒤 적절한 층으로 안내해줍니다. 이처럼 API Gateway도 외부에서 들어오는 모든 요청을 받아서, 인증을 확인하고, 적절한 Lambda 함수나 백엔드 서비스로 연결해주는 역할을 합니다.

API Gateway가 없던 시절에는 어땠을까요? 개발자들은 웹 서버를 직접 구축하고, 로드 밸런서를 설정하고, SSL 인증서를 관리해야 했습니다.

트래픽이 급증하면 서버가 다운되기도 했고, 보안 설정을 하나하나 직접 챙겨야 했습니다. 더 큰 문제는 API 버전 관리였습니다.

새로운 버전을 배포할 때마다 기존 사용자들의 서비스가 중단될 위험이 있었습니다. 바로 이런 문제를 해결하기 위해 API Gateway가 등장했습니다.

API Gateway를 사용하면 서버리스 아키텍처 구축이 가능해집니다. 서버를 직접 관리할 필요가 없어지는 것이죠.

또한 자동으로 확장되기 때문에 트래픽이 갑자기 증가해도 걱정할 필요가 없습니다. 무엇보다 API 키 관리, 사용량 제한, 모니터링까지 모두 자동으로 처리해준다는 큰 이점이 있습니다.

위의 코드를 한 줄씩 살펴보겠습니다. 먼저 AWS SDK를 불러와서 APIGateway 객체를 생성합니다.

이 객체를 통해 API Gateway의 모든 기능을 사용할 수 있습니다. 다음으로 params 객체에 API 이름과 설명, 엔드포인트 타입을 지정합니다.

REGIONAL 타입은 특정 리전에서만 사용하는 일반적인 설정입니다. 마지막으로 createRestApi 메서드를 호출하면, AWS가 자동으로 REST API를 생성하고 고유한 ID를 반환합니다.

실제 현업에서는 어떻게 활용할까요? 예를 들어 모바일 쇼핑몰 앱을 개발한다고 가정해봅시다.

상품 조회, 장바구니 추가, 결제 처리 등 수십 개의 API가 필요합니다. 이 모든 API를 API Gateway 하나로 관리하면, 각 API의 사용량을 모니터링하고, 특정 API에만 인증을 적용하고, 트래픽이 많은 시간대에 자동으로 확장할 수 있습니다.

쿠팡, 배달의민족 같은 대형 서비스에서도 이런 패턴을 적극적으로 사용하고 있습니다. 하지만 주의할 점도 있습니다.

초보 개발자들이 흔히 하는 실수 중 하나는 API Gateway를 Lambda와 혼동하는 것입니다. API Gateway는 단순히 요청을 전달하는 관문일 뿐, 실제 비즈니스 로직은 Lambda나 다른 백엔드 서비스에서 처리됩니다.

또한 API Gateway는 사용량에 따라 과금되므로, 불필요하게 많은 API를 만들면 비용이 증가할 수 있습니다. 따라서 필요한 API만 설계하고, 캐싱 기능을 활용해서 비용을 최적화하는 것이 중요합니다.

다시 김개발 씨의 이야기로 돌아가 봅시다. 박시니어 씨의 설명을 들은 김개발 씨는 고개를 끄덕였습니다.

"아, 그래서 Lambda만으로는 안 되는구나. API Gateway가 정문 역할을 해주는 거네요!" API Gateway를 제대로 이해하면 서버리스 아키텍처를 효율적으로 구축할 수 있습니다.

여러분도 오늘 배운 내용을 실제 프로젝트에 적용해 보세요.

실전 팁

💡 - API Gateway는 Lambda뿐 아니라 EC2, ECS 등 다른 AWS 서비스와도 연동 가능합니다

프리티어로 월 100만 건의 API 호출을 무료로 사용할 수 있으니 부담 없이 연습해보세요
CloudWatch와 자동 연동되어 API 호출 로그를 실시간으로 확인할 수 있습니다

2. REST API 생성

김개발 씨가 AWS 콘솔에 접속해서 API Gateway 메뉴를 열었습니다. "REST API, HTTP API, WebSocket API...

뭐가 이렇게 많지?" 선배 박시니어 씨가 말했습니다. "일반적인 백엔드 API를 만들 거면 REST API를 선택하면 돼요."

REST API는 API Gateway에서 가장 많이 사용되는 API 타입으로, 표준 HTTP 메서드를 사용해서 리소스를 관리합니다. GET, POST, PUT, DELETE 같은 친숙한 메서드로 CRUD 작업을 수행할 수 있으며, 인증, 캐싱, 요청 검증 등 다양한 기능을 제공합니다.

HTTP API보다 기능이 풍부하지만, 그만큼 비용이 조금 더 높습니다.

다음 코드를 살펴봅시다.

// AWS CLI로 REST API 생성
// 터미널에서 실행

// 1. REST API 생성
aws apigateway create-rest-api \
  --name "UserManagementAPI" \
  --description "사용자 관리를 위한 REST API" \
  --endpoint-configuration types=REGIONAL

// 응답 예시:
// {
//   "id": "abc123xyz",  // API ID - 이후 모든 작업에 사용
//   "name": "UserManagementAPI",
//   "createdDate": "2025-12-19T10:00:00Z"
// }

김개발 씨는 이제 본격적으로 API를 만들어보기로 했습니다. AWS 콘솔을 열고 API Gateway 서비스로 들어갔습니다.

화면에는 세 가지 옵션이 보였습니다. REST API, HTTP API, WebSocket API.

"무슨 차이지?" 김개발 씨가 고개를 갸우뚱하자, 박시니어 씨가 설명해줬습니다. "REST API는 기능이 가장 풍부해요.

인증, 캐싱, 요청 변환 같은 걸 다 할 수 있죠. HTTP API는 가볍고 저렴한 대신 기능이 적고, WebSocket API는 실시간 양방향 통신에 쓰이는 거예요." 그렇다면 REST API는 정확히 어떤 특징이 있을까요?

쉽게 비유하자면, REST API는 마치 백화점 같습니다. 모든 층마다 다양한 매장이 있고, 안내 데스크가 있고, VIP 라운지도 있습니다.

반면 HTTP API는 동네 슈퍼마켓 같은 느낌이죠. 필요한 물건은 다 있지만, 부가 서비스는 적습니다.

이처럼 REST API는 엔터프라이즈급 기능이 필요할 때 선택하는 옵션입니다. REST API가 제공하는 주요 기능은 무엇일까요?

첫째, API 키 관리가 가능합니다. 외부 파트너사에게 API를 제공할 때, 각 파트너마다 고유한 API 키를 발급하고 사용량을 제한할 수 있습니다.

둘째, 요청 검증 기능이 있습니다. 클라이언트가 보낸 요청이 올바른 형식인지 Lambda 함수까지 가기 전에 미리 체크할 수 있습니다.

셋째, 응답 캐싱을 설정할 수 있습니다. 같은 요청이 반복되면 Lambda를 호출하지 않고 캐시된 응답을 바로 돌려줘서 비용과 지연시간을 줄일 수 있습니다.

위의 코드를 한 줄씩 살펴보겠습니다. AWS CLI를 사용해서 REST API를 생성하는 명령어입니다.

create-rest-api 명령어에 API 이름과 설명을 전달합니다. endpoint-configuration에서 types=REGIONAL을 지정하면, 이 API는 특정 리전(예: ap-northeast-2, 서울)에서만 동작합니다.

명령을 실행하면 AWS가 고유한 API ID를 반환하는데, 이 ID는 앞으로 리소스를 추가하고 메서드를 만들고 배포할 때 계속 사용됩니다. 실제 현업에서는 어떻게 활용할까요?

예를 들어 핀테크 스타트업에서 금융 API를 개발한다고 가정해봅시다. 계좌 조회, 송금, 거래 내역 조회 같은 민감한 작업들을 처리합니다.

이런 경우 REST API의 요청 검증 기능으로 잘못된 요청을 필터링하고, API 키로 인증된 클라이언트만 접근하도록 제한하고, CloudWatch로 모든 API 호출을 로깅할 수 있습니다. 토스, 카카오페이 같은 서비스에서도 이런 보안 기능을 필수로 사용합니다.

하지만 주의할 점도 있습니다. 초보 개발자들이 흔히 하는 실수 중 하나는 REST API와 HTTP API를 혼동하는 것입니다.

REST API는 요청당 비용이 HTTP API보다 약간 높습니다. 만약 단순히 Lambda를 호출하기만 하는 간단한 API라면, HTTP API가 더 경제적일 수 있습니다.

하지만 인증, 캐싱, 사용량 제한 같은 기능이 필요하다면 REST API를 선택해야 합니다. 따라서 프로젝트 요구사항을 먼저 파악한 뒤 적절한 타입을 선택하는 것이 중요합니다.

또 하나 주의할 점은 API 이름입니다. 한 번 만든 API의 이름은 나중에 변경하기 어렵습니다.

따라서 처음부터 명확하고 일관된 네이밍 규칙을 정하는 것이 좋습니다. 예를 들어 "UserAPI", "ProductAPI"처럼 도메인별로 이름을 짓거나, "v1-user-api"처럼 버전을 포함시키는 방법도 있습니다.

다시 김개발 씨의 이야기로 돌아가 봅시다. 박시니어 씨의 조언을 듣고, 김개발 씨는 자신있게 REST API를 선택했습니다.

"우리 서비스는 나중에 API 키 관리도 필요할 것 같으니까, REST API가 맞겠다!" REST API 생성은 첫 단추입니다. 이제 이 API에 실제로 동작할 리소스와 메서드를 추가할 차례입니다.

여러분도 오늘 배운 내용을 바탕으로 첫 번째 REST API를 만들어보세요.

실전 팁

💡 - REST API 이름은 나중에 변경하기 어려우니 처음부터 신중하게 지으세요

개발용과 운영용 API를 분리해서 관리하면 안전합니다
API Gateway 콘솔에서 클릭 몇 번으로도 생성 가능하지만, CLI나 CloudFormation으로 코드화하면 재현성이 높아집니다

3. 리소스와 메서드

API를 만들었으니 이제 실제 엔드포인트를 추가할 차례입니다. 김개발 씨가 물었습니다.

"그런데 리소스와 메서드가 뭔가요?" 박시니어 씨가 화이트보드에 URL을 그리며 설명했습니다. "/users가 리소스고, GET이나 POST가 메서드예요."

리소스는 API의 경로를 나타내며, URL의 패스 부분에 해당합니다. 메서드는 각 리소스에서 수행할 수 있는 HTTP 동작(GET, POST, PUT, DELETE 등)을 의미합니다.

예를 들어 /users 리소스에 GET 메서드를 추가하면, 사용자 목록을 조회하는 엔드포인트가 됩니다. 리소스는 계층 구조로 만들 수 있어서 /users/{userId}/orders처럼 중첩된 경로도 가능합니다.

다음 코드를 살펴봅시다.

// 1. 루트 리소스 ID 가져오기
aws apigateway get-resources \
  --rest-api-id abc123xyz

// 2. /users 리소스 생성
aws apigateway create-resource \
  --rest-api-id abc123xyz \
  --parent-id xyz789  \
  --path-part users

// 3. GET 메서드 추가
aws apigateway put-method \
  --rest-api-id abc123xyz \
  --resource-id res456 \
  --http-method GET \
  --authorization-type NONE  # 인증 없음

김개발 씨는 REST API를 만들었지만, 아직 아무 기능도 없는 빈 껍데기 상태입니다. "이제 뭘 해야 하죠?" 박시니어 씨가 답했습니다.

"리소스를 추가해야죠. 그게 URL 경로예요." 그렇다면 리소스와 메서드는 정확히 무엇일까요?

쉽게 비유하자면, 리소스는 마치 도서관의 책장 위치와 같습니다. "2층 인문학 코너"가 리소스라면, "책을 빌린다", "책을 반납한다"가 메서드입니다.

도서관에 가서 책을 빌리려면 먼저 어느 책장인지 알아야 하고(리소스), 그 다음에 무슨 행동을 할지(메서드) 정해야 합니다. 이처럼 API도 먼저 경로를 정하고, 그 경로에서 어떤 동작을 할지 지정하는 구조입니다.

API Gateway에서 리소스는 어떻게 구성될까요? 모든 API는 루트 리소스(/)로 시작합니다.

여기에 /users, /products처럼 하위 리소스를 추가할 수 있습니다. 더 나아가서 /users/{userId}처럼 경로 파라미터를 포함한 리소스도 만들 수 있습니다.

중괄호 안의 userId는 동적으로 변하는 값입니다. 예를 들어 /users/123, /users/456처럼 실제 사용자 ID가 들어갑니다.

이런 구조를 RESTful 설계라고 부릅니다. 메서드는 어떤 종류가 있을까요?

가장 많이 사용하는 메서드는 네 가지입니다. GET은 데이터를 조회할 때, POST는 새로운 데이터를 생성할 때, PUT은 기존 데이터를 수정할 때, DELETE는 데이터를 삭제할 때 사용합니다.

예를 들어 /users 리소스에 GET 메서드를 추가하면 사용자 목록 조회 API가 되고, POST 메서드를 추가하면 새 사용자 등록 API가 됩니다. 하나의 리소스에 여러 메서드를 동시에 추가할 수 있습니다.

위의 코드를 한 줄씩 살펴보겠습니다. 먼저 get-resources 명령으로 API의 루트 리소스 ID를 확인합니다.

모든 리소스는 부모 리소스 ID가 필요하기 때문입니다. 다음으로 create-resource 명령으로 /users 리소스를 생성합니다.

parent-id는 루트 리소스의 ID를 넣고, path-part는 실제 경로 이름인 "users"를 입력합니다. 마지막으로 put-method 명령으로 GET 메서드를 추가합니다.

authorization-type을 NONE으로 설정하면 인증 없이 누구나 호출할 수 있는 공개 API가 됩니다. 실제 현업에서는 어떻게 활용할까요?

예를 들어 블로그 서비스를 개발한다고 가정해봅시다. /posts 리소스에 GET 메서드를 추가해서 게시글 목록을 조회하고, POST 메서드로 새 게시글을 작성하고, /posts/{postId} 리소스에 PUT 메서드로 게시글을 수정하고, DELETE 메서드로 삭제하는 식입니다.

이런 구조는 직관적이고 이해하기 쉬워서, 프론트엔드 개발자나 외부 파트너가 API 문서를 보고 바로 사용할 수 있습니다. 네이버 블로그, 티스토리 같은 서비스의 API도 이런 RESTful 패턴을 따릅니다.

하지만 주의할 점도 있습니다. 초보 개발자들이 흔히 하는 실수 중 하나는 리소스 이름을 동사로 짓는 것입니다.

예를 들어 /getUsers, /createUser처럼 만드는 경우인데, 이는 REST 원칙에 맞지 않습니다. 리소스는 명사여야 하고, 동작은 메서드로 표현해야 합니다.

따라서 /users 리소스에 GET, POST 메서드를 추가하는 것이 올바른 설계입니다. 또 하나 주의할 점은 경로 파라미터입니다.

/users/{userId}처럼 만들 때, 중괄호 안의 이름은 나중에 Lambda 함수에서 그대로 사용됩니다. 따라서 일관된 네이밍을 유지하는 것이 중요합니다.

userId, user_id, id 같은 이름이 섞여 있으면 코드가 복잡해집니다. 다시 김개발 씨의 이야기로 돌아가 봅시다.

박시니어 씨의 설명을 들은 김개발 씨는 직접 /users 리소스를 만들고, GET과 POST 메서드를 추가했습니다. "오, 이제 진짜 API처럼 보이네요!" 리소스와 메서드는 API의 뼈대입니다.

이제 이 API를 실제로 Lambda 함수와 연결하고 배포하면 동작하는 API가 됩니다. 여러분도 오늘 배운 내용을 바탕으로 RESTful한 리소스 구조를 설계해보세요.

실전 팁

💡 - 리소스 이름은 복수형 명사를 사용하세요 (/user가 아니라 /users)

경로 파라미터 이름은 camelCase나 snake_case 중 하나로 통일하세요
OPTIONS 메서드는 CORS 설정 시 자동으로 필요하니 미리 추가해두면 좋습니다

4. 스테이지 개념

김개발 씨가 API를 만들고 배포하려는데, 화면에 "스테이지 이름을 입력하세요"라는 메시지가 떴습니다. "스테이지가 뭐죠?" 박시니어 씨가 설명했습니다.

"개발용, 테스트용, 운영용처럼 환경을 분리하는 거예요."

스테이지는 API의 배포 환경을 구분하는 개념으로, dev, test, prod처럼 여러 버전을 동시에 관리할 수 있게 해줍니다. 같은 API라도 개발 단계에서는 dev 스테이지로 배포하고, 실제 서비스에는 prod 스테이지로 배포해서 안전하게 운영할 수 있습니다.

각 스테이지는 독립된 URL을 가지며, 설정도 개별적으로 관리됩니다.

다음 코드를 살펴봅시다.

// 1. API를 dev 스테이지로 배포
aws apigateway create-deployment \
  --rest-api-id abc123xyz \
  --stage-name dev \
  --stage-description "개발 환경" \
  --description "첫 배포"

// 배포 후 엔드포인트 URL:
// https://abc123xyz.execute-api.ap-northeast-2.amazonaws.com/dev/users

// 2. 스테이지 설정 확인
aws apigateway get-stage \
  --rest-api-id abc123xyz \
  --stage-name dev

김개발 씨는 리소스와 메서드까지 모두 만들었습니다. "이제 배포만 하면 되겠다!" 하지만 콘솔 화면에 "스테이지 이름"을 입력하라는 필드가 나타났습니다.

"뭘 입력해야 하지?" 박시니어 씨가 웃으며 말했습니다. "스테이지를 모르고 배포하려고 했구나.

그럼 개발 중인 API가 바로 운영 환경에 올라갈 수도 있어요." 그렇다면 스테이지는 정확히 무엇일까요? 쉽게 비유하자면, 스테이지는 마치 연극 무대와 같습니다.

같은 연극이라도 리허설 무대, 프리뷰 무대, 정식 공연 무대가 따로 있습니다. 리허설 무대에서는 실수해도 괜찮지만, 정식 공연 무대에서는 완벽해야 합니다.

이처럼 API도 개발 스테이지에서는 자유롭게 테스트하고, 운영 스테이지에서는 안정적으로 서비스하는 방식으로 환경을 분리합니다. 스테이지는 왜 필요할까요?

개발자는 새로운 기능을 만들 때 여러 번 시도하고 실패합니다. 만약 스테이지 없이 모든 변경사항이 바로 운영 환경에 반영된다면, 사용자들이 에러를 겪게 됩니다.

하지만 dev 스테이지에서 충분히 테스트하고, test 스테이지에서 QA를 거친 뒤, 마지막으로 prod 스테이지에 배포하면 안전합니다. 또한 각 스테이지마다 다른 Lambda 함수를 연결하거나, 다른 데이터베이스를 사용할 수도 있습니다.

스테이지는 어떻게 구성될까요? 일반적으로 세 가지 스테이지를 만듭니다.

dev 스테이지는 개발자가 자유롭게 실험하는 환경입니다. 코드를 수정할 때마다 바로바로 배포해서 확인합니다.

test 스테이지는 QA 팀이 테스트하는 환경입니다. 기능이 제대로 동작하는지, 엣지 케이스는 없는지 검증합니다.

prod 스테이지는 실제 사용자가 접근하는 운영 환경입니다. 철저히 검증된 코드만 배포하며, 모니터링과 알람을 설정해서 문제가 생기면 즉시 대응합니다.

위의 코드를 한 줄씩 살펴보겠습니다. create-deployment 명령으로 API를 dev 스테이지에 배포합니다.

stage-name에 "dev"를 입력하면, AWS가 자동으로 dev 스테이지를 생성하고 배포합니다. 배포가 완료되면 고유한 URL이 생성되는데, 이 URL에는 API ID와 스테이지 이름이 포함됩니다.

예를 들어 https://abc123xyz.execute-api.ap-northeast-2.amazonaws.com/dev/users처럼 생성됩니다. 이 URL을 브라우저나 Postman에서 호출하면 실제로 API가 동작합니다.

실제 현업에서는 어떻게 활용할까요? 예를 들어 이커머스 플랫폼을 개발하는 팀이 있다고 가정해봅시다.

신규 결제 기능을 추가할 때, 먼저 dev 스테이지에서 개발자가 직접 테스트합니다. 문제가 없으면 test 스테이지에 배포해서 QA 팀이 시나리오 테스트를 진행합니다.

모든 테스트를 통과하면, 마지막으로 prod 스테이지에 배포해서 실제 고객이 사용하게 됩니다. 만약 prod 스테이지에서 문제가 발견되면, 이전 버전의 배포로 즉시 롤백할 수 있습니다.

쿠팡, 11번가 같은 대형 쇼핑몰에서도 이런 다단계 배포 전략을 사용합니다. 하지만 주의할 점도 있습니다.

초보 개발자들이 흔히 하는 실수 중 하나는 모든 스테이지에서 같은 Lambda 함수를 사용하는 것입니다. 이렇게 하면 dev 스테이지에서 테스트하다가 운영 데이터베이스를 건드릴 수 있습니다.

따라서 각 스테이지마다 다른 Lambda 함수 별칭(alias)을 연결하거나, 환경 변수로 데이터베이스 연결 정보를 다르게 설정해야 합니다. 또 하나 주의할 점은 스테이지 변수입니다.

스테이지마다 다른 설정값을 주입할 수 있는데, 예를 들어 dev 스테이지에서는 로깅을 상세하게 남기고, prod 스테이지에서는 에러 로그만 남기는 식으로 활용할 수 있습니다. 이런 변수를 잘 활용하면 코드 수정 없이 환경별 설정을 관리할 수 있습니다.

다시 김개발 씨의 이야기로 돌아가 봅시다. 박시니어 씨의 조언을 듣고, 김개발 씨는 dev 스테이지를 만들어서 먼저 배포했습니다.

"아, 이제 안전하게 테스트할 수 있겠네요!" 스테이지는 안전한 배포의 핵심입니다. 개발, 테스트, 운영 환경을 분리해서 관리하면 장애를 예방할 수 있습니다.

여러분도 오늘 배운 내용을 바탕으로 스테이지 전략을 세워보세요.

실전 팁

💡 - 스테이지 이름은 짧고 명확하게 (dev, test, prod 같은 표준 네이밍 추천)

각 스테이지마다 다른 Lambda 별칭을 연결해서 환경을 완전히 분리하세요
스테이지 변수를 활용하면 환경별 설정을 코드 수정 없이 관리할 수 있습니다

5. API 배포하기

김개발 씨가 드디어 API를 완성했습니다. "이제 배포만 하면 되는데, 버튼 하나면 되겠죠?" 박시니어 씨가 고개를 저었습니다.

"배포는 신중하게 해야 해요. 한 번 배포하면 URL이 바뀌지 않으니까요."

API 배포는 작성한 리소스와 메서드를 실제로 사용 가능한 상태로 만드는 과정입니다. 배포하기 전까지는 API가 동작하지 않으며, 배포할 때마다 새로운 배포 버전이 생성됩니다.

스테이지를 선택해서 배포하면 해당 스테이지의 URL로 API에 접근할 수 있게 되고, 배포 히스토리가 자동으로 관리되어 필요할 때 이전 버전으로 롤백할 수 있습니다.

다음 코드를 살펴봅시다.

// 1. dev 스테이지로 배포
aws apigateway create-deployment \
  --rest-api-id abc123xyz \
  --stage-name dev \
  --description "사용자 조회 기능 추가"

// 2. 배포 기록 확인
aws apigateway get-deployments \
  --rest-api-id abc123xyz

// 3. 특정 배포 ID로 롤백
aws apigateway update-stage \
  --rest-api-id abc123xyz \
  --stage-name dev \
  --patch-operations op=replace,path=/deploymentId,value=deploy123

김개발 씨는 /users 리소스에 GET 메서드를 추가하고, Lambda 함수도 연결했습니다. "이제 다 됐다!" 하지만 URL을 복사해서 브라우저에 입력했더니 404 에러가 났습니다.

"왜 안 되지?" 박시니어 씨가 화면을 보더니 말했습니다. "아, 배포를 안 했네요.

API Gateway는 변경사항을 저장하기만 하고, 배포를 해야 실제로 적용돼요." 그렇다면 API 배포는 정확히 무엇일까요? 쉽게 비유하자면, API 배포는 마치 책을 출판하는 것과 같습니다.

원고를 아무리 잘 써도, 인쇄하고 서점에 배포하기 전까지는 독자가 읽을 수 없습니다. 이처럼 API도 리소스와 메서드를 아무리 잘 만들어도, 배포하기 전까지는 외부에서 접근할 수 없습니다.

배포 버튼을 누르는 순간, AWS가 모든 설정을 적용하고 URL을 활성화합니다. 배포는 어떤 과정으로 진행될까요?

먼저 배포할 스테이지를 선택합니다. dev 스테이지로 배포할지, prod 스테이지로 배포할지 정하는 것이죠.

다음으로 배포 설명을 입력합니다. "사용자 조회 기능 추가", "버그 수정" 같은 메모를 남기면 나중에 배포 기록을 확인할 때 유용합니다.

마지막으로 배포를 실행하면, AWS가 모든 리소스와 메서드 설정을 스테이지에 반영하고 고유한 배포 ID를 생성합니다. 배포 후에는 무엇이 달라질까요?

배포가 완료되면 스테이지별 URL이 활성화됩니다. 예를 들어 dev 스테이지로 배포했다면, https://abc123xyz.execute-api.ap-northeast-2.amazonaws.com/dev/users 같은 URL이 생성됩니다.

이 URL을 클라이언트에게 전달하면, 브라우저나 모바일 앱에서 바로 API를 호출할 수 있습니다. 또한 배포 히스토리가 자동으로 기록되어, 언제 누가 무엇을 배포했는지 추적할 수 있습니다.

위의 코드를 한 줄씩 살펴보겠습니다. create-deployment 명령으로 dev 스테이지에 배포합니다.

description 항목에 "사용자 조회 기능 추가"처럼 의미 있는 메시지를 남기면, 나중에 배포 기록을 볼 때 어떤 변경사항이 포함되었는지 알 수 있습니다. get-deployments 명령으로 배포 기록을 확인할 수 있으며, 각 배포마다 고유한 ID가 부여됩니다.

만약 최신 배포에서 문제가 발생하면, update-stage 명령으로 이전 배포 ID를 지정해서 롤백할 수 있습니다. 실제 현업에서는 어떻게 활용할까요?

예를 들어 배달 앱 서비스를 운영하는 팀이 있다고 가정해봅시다. 신규 쿠폰 기능을 추가할 때, 먼저 dev 스테이지에 배포해서 개발팀이 테스트합니다.

문제가 없으면 test 스테이지에 배포해서 QA 팀이 검증합니다. 모든 테스트를 통과하면 금요일 저녁이 아닌 월요일 오전에 prod 스테이지로 배포합니다.

왜냐하면 만약 문제가 생기면 즉시 대응할 수 있는 시간대가 안전하기 때문입니다. 배달의민족, 쿠팡이츠 같은 서비스에서도 이런 배포 전략을 사용합니다.

하지만 주의할 점도 있습니다. 초보 개발자들이 흔히 하는 실수 중 하나는 배포 설명을 생략하는 것입니다.

"배포 1", "배포 2"처럼 의미 없는 메시지만 남기면, 나중에 문제가 생겼을 때 어느 배포가 원인인지 찾기 어렵습니다. 따라서 "결제 API 응답 시간 개선", "로그인 버그 수정"처럼 구체적인 설명을 남기는 습관이 중요합니다.

또 하나 주의할 점은 배포 타이밍입니다. 운영 환경에 배포할 때는 트래픽이 적은 시간대를 선택하는 것이 안전합니다.

만약 점심시간이나 저녁시간처럼 사용자가 많을 때 배포했다가 문제가 생기면, 많은 사용자가 피해를 입습니다. 따라서 새벽 시간이나 이른 아침에 배포하고, 30분 정도 모니터링한 뒤 문제가 없으면 퇴근하는 것이 좋습니다.

다시 김개발 씨의 이야기로 돌아가 봅시다. 박시니어 씨의 조언을 듣고, 김개발 씨는 배포 설명을 "첫 번째 사용자 조회 API 배포"라고 작성하고 dev 스테이지에 배포했습니다.

URL을 다시 호출했더니 이번에는 제대로 동작했습니다. "드디어 성공했다!" API 배포는 개발의 마지막 단계입니다.

배포 설명을 잘 작성하고, 적절한 시간에 배포하고, 배포 후 모니터링하는 습관을 들이면 안정적인 서비스를 운영할 수 있습니다. 여러분도 오늘 배운 내용을 바탕으로 첫 배포를 진행해보세요.

실전 팁

💡 - 배포 설명은 Jira 티켓 번호나 커밋 해시를 포함하면 추적하기 쉽습니다

운영 배포는 트래픽이 적은 새벽이나 이른 아침에 진행하세요
배포 후 CloudWatch 로그를 30분 정도 모니터링해서 에러가 없는지 확인하세요

6. API 키와 사용량 계획

API를 성공적으로 배포한 김개발 씨에게 팀장이 요청했습니다. "외부 파트너사에게 API를 제공하는데, 사용량을 제한할 방법이 있나요?" 김개발 씨가 당황하자, 박시니어 씨가 말했습니다.

"API 키와 사용량 계획을 설정하면 돼요."

API 키는 외부 클라이언트를 식별하는 고유한 문자열로, API 호출 시 헤더에 포함시켜 인증합니다. 사용량 계획은 API 키별로 호출 횟수를 제한하는 정책으로, 초당 요청 수와 일일 최대 호출 수를 설정할 수 있습니다.

예를 들어 무료 플랜은 하루 1000건, 유료 플랜은 하루 10000건처럼 차등 제한을 두면, 과도한 트래픽을 방지하고 수익 모델을 만들 수 있습니다.

다음 코드를 살펴봅시다.

// 1. 사용량 계획 생성
aws apigateway create-usage-plan \
  --name "BasicPlan" \
  --description "무료 사용자 플랜" \
  --throttle rateLimit=10,burstLimit=20 \
  --quota limit=1000,period=DAY

// 2. API 키 생성
aws apigateway create-api-key \
  --name "PartnerA-Key" \
  --description "파트너사 A의 API 키" \
  --enabled

// 3. API 키를 사용량 계획에 연결
aws apigateway create-usage-plan-key \
  --usage-plan-id plan123 \
  --key-id key456 \
  --key-type API_KEY

김개발 씨는 API를 성공적으로 배포했고, 사내 프론트엔드 팀이 잘 사용하고 있습니다. 그런데 팀장이 새로운 요청을 했습니다.

"외부 파트너사 세 곳에 API를 제공하려고 하는데, 각 파트너마다 사용량을 다르게 제한할 수 있나요?" 김개발 씨는 당황했습니다. "어떻게 그걸 구분하지?" 박시니어 씨가 화이트보드에 그림을 그리며 설명했습니다.

"API 키로 파트너를 구분하고, 사용량 계획으로 제한을 걸면 돼요." 그렇다면 API 키와 사용량 계획은 정확히 무엇일까요? 쉽게 비유하자면, API 키는 마치 회원 카드와 같습니다.

스타벅스에 가면 일반 회원, 골드 회원, VIP 회원처럼 등급이 있고, 각 등급마다 혜택이 다릅니다. API 키도 마찬가지입니다.

파트너 A는 하루 1000건, 파트너 B는 하루 5000건처럼 각각 다른 사용량 제한을 받습니다. 사용량 계획은 이런 등급별 정책을 정의하는 것입니다.

API 키는 왜 필요할까요? 만약 API가 공개되어 있고 제한이 없다면, 누군가 악의적으로 수백만 건의 요청을 보낼 수 있습니다.

그러면 Lambda 함수 비용이 폭증하고, 정상 사용자들은 느린 응답을 겪게 됩니다. API 키를 사용하면 등록된 파트너만 접근할 수 있고, 파트너별로 사용량을 추적할 수 있습니다.

또한 특정 파트너가 약정한 호출 수를 초과하면 자동으로 차단할 수 있습니다. 사용량 계획은 어떻게 구성될까요?

사용량 계획에는 세 가지 주요 설정이 있습니다. Rate Limit은 초당 평균 요청 수입니다.

예를 들어 10으로 설정하면, 1초에 평균 10건의 요청만 허용합니다. Burst Limit은 짧은 시간에 허용되는 최대 요청 수입니다.

20으로 설정하면, 순간적으로 20건까지는 허용하지만 그 이상은 거부합니다. Quota는 일일 또는 월별 총 요청 수입니다.

1000으로 설정하면, 하루에 1000건을 초과하는 순간부터 요청이 차단됩니다. 위의 코드를 한 줄씩 살펴보겠습니다.

먼저 create-usage-plan 명령으로 "BasicPlan"이라는 무료 사용자 플랜을 만듭니다. throttle 옵션에서 rateLimit=10은 초당 평균 10건, burstLimit=20은 순간 최대 20건을 의미합니다.

quota 옵션에서 limit=1000은 하루 최대 1000건, period=DAY는 일일 제한을 의미합니다. 다음으로 create-api-key 명령으로 "PartnerA-Key"라는 API 키를 생성합니다.

마지막으로 create-usage-plan-key 명령으로 이 API 키를 BasicPlan에 연결하면, 파트너 A가 API를 호출할 때 자동으로 제한이 적용됩니다. 실제 현업에서는 어떻게 활용할까요?

예를 들어 날씨 정보 API를 제공하는 스타트업이 있다고 가정해봅시다. 무료 플랜은 하루 100건, 기본 플랜은 하루 1000건, 프리미엄 플랜은 하루 10000건으로 차등 제한을 둡니다.

각 고객사에게 API 키를 발급할 때, 플랜에 따라 다른 사용량 계획을 연결합니다. 고객이 한도를 초과하면 자동으로 429 에러(Too Many Requests)가 반환되고, 업그레이드를 유도할 수 있습니다.

네이버 클라우드, 카카오 개발자센터에서도 이런 방식으로 API를 제공합니다. 하지만 주의할 점도 있습니다.

초보 개발자들이 흔히 하는 실수 중 하나는 API 키를 코드에 하드코딩하는 것입니다. 예를 들어 프론트엔드 JavaScript 파일에 API 키를 직접 넣으면, 누구나 브라우저 개발자 도구로 볼 수 있습니다.

따라서 API 키는 반드시 서버 사이드에서 관리하고, 클라이언트에는 노출하지 않아야 합니다. 프론트엔드에서 API를 호출할 때는 백엔드 서버를 경유하도록 설계하는 것이 안전합니다.

또 하나 주의할 점은 사용량 계획의 기간입니다. DAY, WEEK, MONTH 중 하나를 선택할 수 있는데, 고객의 사용 패턴을 고려해야 합니다.

예를 들어 월 초에 트래픽이 몰리는 서비스라면, 일일 제한보다 월간 제한이 더 적합할 수 있습니다. 반대로 트래픽이 일정한 서비스라면, 일일 제한으로 세밀하게 관리하는 것이 좋습니다.

다시 김개발 씨의 이야기로 돌아가 봅시다. 박시니어 씨의 조언을 듣고, 김개발 씨는 파트너사별로 API 키를 발급하고 사용량 계획을 연결했습니다.

팀장이 만족스러워하며 말했습니다. "이제 안심하고 외부에 API를 제공할 수 있겠네요!" API 키와 사용량 계획은 API를 상품화하는 핵심 기능입니다.

무료 플랜과 유료 플랜을 구분하고, 악의적인 트래픽을 차단하고, 수익 모델을 만들 수 있습니다. 여러분도 오늘 배운 내용을 바탕으로 API 비즈니스 모델을 설계해보세요.

실전 팁

💡 - API 키는 절대 클라이언트 코드에 하드코딩하지 마세요 (서버에서만 사용)

사용량 계획은 무료, 기본, 프리미엄처럼 3단계 정도로 구분하면 관리하기 쉽습니다
CloudWatch에서 API 키별 사용량을 모니터링해서 업그레이드 시점을 파악하세요

이상으로 학습을 마칩니다. 위 내용을 직접 코드로 작성해보면서 익혀보세요!

#AWS#APIGateway#REST#Lambda#CloudService

AWS API Gateway REST API 완벽 가이드

# AWS API Gateway REST API 완벽 가이드 AWS API Gateway로 REST API를 만들고 배포하는 전 과정을 다룹니다. 초급 개발자도 쉽게 따라할 수 있도록 실무 상황을 스토리로 풀어냈습니다. API Gateway의 핵심 개념부터 실제 배포까지 단계별로 학습합니다. --- ## 목차 1. [API Gateway란?](#api-gateway란?) 2. [REST API 생성](#rest-api-생성) 3. [리소스와 메서드](#리소스와-메서드) 4. [스테이지 개념](#스테이지-개념) 5. [API 배포하기](#api-배포하기) 6. [API 키와 사용량 계획](#api-키와-사용량-계획) --- ## 1. API Gateway란? 이제 막 백엔드 개발을 시작한 김개발 씨가 선배에게 질문했습니다. "Lambda 함수는 만들었는데, 이걸 어떻게 외부에서 호출하나요?" 선배 박시니어 씨가 웃으며 대답했습니다. "바로 그럴 때 API Gateway가 필요하지." **API Gateway**는 AWS의 관리형 서비스로, REST API를 쉽게 생성하고 관리할 수 있게 해줍니다. 마치 건물의 정문 경비원처럼, 외부 요청을 받아서 적절한 Lambda 함수나 백엔드 서비스로 연결해주는 역할을 합니다. 인증, 모니터링, 트래픽 관리까지 자동으로 처리해주기 때문에 개발자는 비즈니스 로직에만 집중할 수 있습니다. 다음 코드를 살펴봅시다. ```javascript // API Gateway를 통해 Lambda 함수 호출하는 예제 const AWS = require('aws-sdk'); const apigateway = new AWS.APIGateway(); // REST API 생성 const params = { name: 'MyFirstAPI', description: '첫 번째 REST API 생성', endpointConfiguration: { types: ['REGIONAL'] // 리전별 엔드포인트 } }; apigateway.createRestApi(params, (err, data) => { if (err) console.log(err); else console.log('API ID:', data.id); // API ID 출력 }); ``` 김개발 씨는 입사 2개월 차 주니어 개발자입니다. Lambda 함수로 간단한 사용자 조회 기능을 만들었지만, 막상 프론트엔드 팀에게 어떻게 전달해야 할지 막막했습니다. "이 Lambda 함수를 어떻게 호출하라고 하지?" 박시니어 씨가 옆자리에서 화면을 살짝 보더니 말했습니다. "아, Lambda 함수만 있고 API Gateway가 없네요. 그럼 외부에서 접근할 수가 없어요." 그렇다면 **API Gateway**란 정확히 무엇일까요? 쉽게 비유하자면, API Gateway는 마치 대형 건물의 정문 경비실과 같습니다. 방문객이 건물에 들어오려면 반드시 정문을 거쳐야 하고, 경비원이 신분을 확인한 뒤 적절한 층으로 안내해줍니다. 이처럼 API Gateway도 외부에서 들어오는 모든 요청을 받아서, 인증을 확인하고, 적절한 Lambda 함수나 백엔드 서비스로 연결해주는 역할을 합니다. API Gateway가 없던 시절에는 어땠을까요? 개발자들은 웹 서버를 직접 구축하고, 로드 밸런서를 설정하고, SSL 인증서를 관리해야 했습니다. 트래픽이 급증하면 서버가 다운되기도 했고, 보안 설정을 하나하나 직접 챙겨야 했습니다. 더 큰 문제는 API 버전 관리였습니다. 새로운 버전을 배포할 때마다 기존 사용자들의 서비스가 중단될 위험이 있었습니다. 바로 이런 문제를 해결하기 위해 **API Gateway**가 등장했습니다. API Gateway를 사용하면 서버리스 아키텍처 구축이 가능해집니다. 서버를 직접 관리할 필요가 없어지는 것이죠. 또한 자동으로 확장되기 때문에 트래픽이 갑자기 증가해도 걱정할 필요가 없습니다. 무엇보다 API 키 관리, 사용량 제한, 모니터링까지 모두 자동으로 처리해준다는 큰 이점이 있습니다. 위의 코드를 한 줄씩 살펴보겠습니다. 먼저 AWS SDK를 불러와서 APIGateway 객체를 생성합니다. 이 객체를 통해 API Gateway의 모든 기능을 사용할 수 있습니다. 다음으로 params 객체에 API 이름과 설명, 엔드포인트 타입을 지정합니다. REGIONAL 타입은 특정 리전에서만 사용하는 일반적인 설정입니다. 마지막으로 createRestApi 메서드를 호출하면, AWS가 자동으로 REST API를 생성하고 고유한 ID를 반환합니다. 실제 현업에서는 어떻게 활용할까요? 예를 들어 모바일 쇼핑몰 앱을 개발한다고 가정해봅시다. 상품 조회, 장바구니 추가, 결제 처리 등 수십 개의 API가 필요합니다. 이 모든 API를 API Gateway 하나로 관리하면, 각 API의 사용량을 모니터링하고, 특정 API에만 인증을 적용하고, 트래픽이 많은 시간대에 자동으로 확장할 수 있습니다. 쿠팡, 배달의민족 같은 대형 서비스에서도 이런 패턴을 적극적으로 사용하고 있습니다. 하지만 주의할 점도 있습니다. 초보 개발자들이 흔히 하는 실수 중 하나는 API Gateway를 Lambda와 혼동하는 것입니다. API Gateway는 단순히 요청을 전달하는 관문일 뿐, 실제 비즈니스 로직은 Lambda나 다른 백엔드 서비스에서 처리됩니다. 또한 API Gateway는 사용량에 따라 과금되므로, 불필요하게 많은 API를 만들면 비용이 증가할 수 있습니다. 따라서 필요한 API만 설계하고, 캐싱 기능을 활용해서 비용을 최적화하는 것이 중요합니다. 다시 김개발 씨의 이야기로 돌아가 봅시다. 박시니어 씨의 설명을 들은 김개발 씨는 고개를 끄덕였습니다. "아, 그래서 Lambda만으로는 안 되는구나. API Gateway가 정문 역할을 해주는 거네요!" API Gateway를 제대로 이해하면 서버리스 아키텍처를 효율적으로 구축할 수 있습니다. 여러분도 오늘 배운 내용을 실제 프로젝트에 적용해 보세요. **실전 팁** 💡 - API Gateway는 Lambda뿐 아니라 EC2, ECS 등 다른 AWS 서비스와도 연동 가능합니다 - 프리티어로 월 100만 건의 API 호출을 무료로 사용할 수 있으니 부담 없이 연습해보세요 - CloudWatch와 자동 연동되어 API 호출 로그를 실시간으로 확인할 수 있습니다 --- ## 2. REST API 생성 김개발 씨가 AWS 콘솔에 접속해서 API Gateway 메뉴를 열었습니다. "REST API, HTTP API, WebSocket API... 뭐가 이렇게 많지?" 선배 박시니어 씨가 말했습니다. "일반적인 백엔드 API를 만들 거면 REST API를 선택하면 돼요." **REST API**는 API Gateway에서 가장 많이 사용되는 API 타입으로, 표준 HTTP 메서드를 사용해서 리소스를 관리합니다. GET, POST, PUT, DELETE 같은 친숙한 메서드로 CRUD 작업을 수행할 수 있으며, 인증, 캐싱, 요청 검증 등 다양한 기능을 제공합니다. HTTP API보다 기능이 풍부하지만, 그만큼 비용이 조금 더 높습니다. 다음 코드를 살펴봅시다. ```javascript // AWS CLI로 REST API 생성 // 터미널에서 실행 // 1. REST API 생성 aws apigateway create-rest-api \ --name "UserManagementAPI" \ --description "사용자 관리를 위한 REST API" \ --endpoint-configuration types=REGIONAL // 응답 예시: // { // "id": "abc123xyz", // API ID - 이후 모든 작업에 사용 // "name": "UserManagementAPI", // "createdDate": "2025-12-19T10:00:00Z" // } ``` 김개발 씨는 이제 본격적으로 API를 만들어보기로 했습니다. AWS 콘솔을 열고 API Gateway 서비스로 들어갔습니다. 화면에는 세 가지 옵션이 보였습니다. REST API, HTTP API, WebSocket API. "무슨 차이지?" 김개발 씨가 고개를 갸우뚱하자, 박시니어 씨가 설명해줬습니다. "REST API는 기능이 가장 풍부해요. 인증, 캐싱, 요청 변환 같은 걸 다 할 수 있죠. HTTP API는 가볍고 저렴한 대신 기능이 적고, WebSocket API는 실시간 양방향 통신에 쓰이는 거예요." 그렇다면 **REST API**는 정확히 어떤 특징이 있을까요? 쉽게 비유하자면, REST API는 마치 백화점 같습니다. 모든 층마다 다양한 매장이 있고, 안내 데스크가 있고, VIP 라운지도 있습니다. 반면 HTTP API는 동네 슈퍼마켓 같은 느낌이죠. 필요한 물건은 다 있지만, 부가 서비스는 적습니다. 이처럼 REST API는 엔터프라이즈급 기능이 필요할 때 선택하는 옵션입니다. REST API가 제공하는 주요 기능은 무엇일까요? 첫째, **API 키 관리**가 가능합니다. 외부 파트너사에게 API를 제공할 때, 각 파트너마다 고유한 API 키를 발급하고 사용량을 제한할 수 있습니다. 둘째, **요청 검증** 기능이 있습니다. 클라이언트가 보낸 요청이 올바른 형식인지 Lambda 함수까지 가기 전에 미리 체크할 수 있습니다. 셋째, **응답 캐싱**을 설정할 수 있습니다. 같은 요청이 반복되면 Lambda를 호출하지 않고 캐시된 응답을 바로 돌려줘서 비용과 지연시간을 줄일 수 있습니다. 위의 코드를 한 줄씩 살펴보겠습니다. AWS CLI를 사용해서 REST API를 생성하는 명령어입니다. create-rest-api 명령어에 API 이름과 설명을 전달합니다. endpoint-configuration에서 types=REGIONAL을 지정하면, 이 API는 특정 리전(예: ap-northeast-2, 서울)에서만 동작합니다. 명령을 실행하면 AWS가 고유한 API ID를 반환하는데, 이 ID는 앞으로 리소스를 추가하고 메서드를 만들고 배포할 때 계속 사용됩니다. 실제 현업에서는 어떻게 활용할까요? 예를 들어 핀테크 스타트업에서 금융 API를 개발한다고 가정해봅시다. 계좌 조회, 송금, 거래 내역 조회 같은 민감한 작업들을 처리합니다. 이런 경우 REST API의 요청 검증 기능으로 잘못된 요청을 필터링하고, API 키로 인증된 클라이언트만 접근하도록 제한하고, CloudWatch로 모든 API 호출을 로깅할 수 있습니다. 토스, 카카오페이 같은 서비스에서도 이런 보안 기능을 필수로 사용합니다. 하지만 주의할 점도 있습니다. 초보 개발자들이 흔히 하는 실수 중 하나는 REST API와 HTTP API를 혼동하는 것입니다. REST API는 요청당 비용이 HTTP API보다 약간 높습니다. 만약 단순히 Lambda를 호출하기만 하는 간단한 API라면, HTTP API가 더 경제적일 수 있습니다. 하지만 인증, 캐싱, 사용량 제한 같은 기능이 필요하다면 REST API를 선택해야 합니다. 따라서 프로젝트 요구사항을 먼저 파악한 뒤 적절한 타입을 선택하는 것이 중요합니다. 또 하나 주의할 점은 API 이름입니다. 한 번 만든 API의 이름은 나중에 변경하기 어렵습니다. 따라서 처음부터 명확하고 일관된 네이밍 규칙을 정하는 것이 좋습니다. 예를 들어 "UserAPI", "ProductAPI"처럼 도메인별로 이름을 짓거나, "v1-user-api"처럼 버전을 포함시키는 방법도 있습니다. 다시 김개발 씨의 이야기로 돌아가 봅시다. 박시니어 씨의 조언을 듣고, 김개발 씨는 자신있게 REST API를 선택했습니다. "우리 서비스는 나중에 API 키 관리도 필요할 것 같으니까, REST API가 맞겠다!" REST API 생성은 첫 단추입니다. 이제 이 API에 실제로 동작할 리소스와 메서드를 추가할 차례입니다. 여러분도 오늘 배운 내용을 바탕으로 첫 번째 REST API를 만들어보세요. **실전 팁** 💡 - REST API 이름은 나중에 변경하기 어려우니 처음부터 신중하게 지으세요 - 개발용과 운영용 API를 분리해서 관리하면 안전합니다 - API Gateway 콘솔에서 클릭 몇 번으로도 생성 가능하지만, CLI나 CloudFormation으로 코드화하면 재현성이 높아집니다 --- ## 3. 리소스와 메서드 API를 만들었으니 이제 실제 엔드포인트를 추가할 차례입니다. 김개발 씨가 물었습니다. "그런데 리소스와 메서드가 뭔가요?" 박시니어 씨가 화이트보드에 URL을 그리며 설명했습니다. "/users가 리소스고, GET이나 POST가 메서드예요." **리소스**는 API의 경로를 나타내며, URL의 패스 부분에 해당합니다. **메서드**는 각 리소스에서 수행할 수 있는 HTTP 동작(GET, POST, PUT, DELETE 등)을 의미합니다. 예를 들어 /users 리소스에 GET 메서드를 추가하면, 사용자 목록을 조회하는 엔드포인트가 됩니다. 리소스는 계층 구조로 만들 수 있어서 /users/{userId}/orders처럼 중첩된 경로도 가능합니다. 다음 코드를 살펴봅시다. ```javascript // 1. 루트 리소스 ID 가져오기 aws apigateway get-resources \ --rest-api-id abc123xyz // 2. /users 리소스 생성 aws apigateway create-resource \ --rest-api-id abc123xyz \ --parent-id xyz789 \ --path-part users // 3. GET 메서드 추가 aws apigateway put-method \ --rest-api-id abc123xyz \ --resource-id res456 \ --http-method GET \ --authorization-type NONE # 인증 없음 ``` 김개발 씨는 REST API를 만들었지만, 아직 아무 기능도 없는 빈 껍데기 상태입니다. "이제 뭘 해야 하죠?" 박시니어 씨가 답했습니다. "리소스를 추가해야죠. 그게 URL 경로예요." 그렇다면 **리소스**와 **메서드**는 정확히 무엇일까요? 쉽게 비유하자면, 리소스는 마치 도서관의 책장 위치와 같습니다. "2층 인문학 코너"가 리소스라면, "책을 빌린다", "책을 반납한다"가 메서드입니다. 도서관에 가서 책을 빌리려면 먼저 어느 책장인지 알아야 하고(리소스), 그 다음에 무슨 행동을 할지(메서드) 정해야 합니다. 이처럼 API도 먼저 경로를 정하고, 그 경로에서 어떤 동작을 할지 지정하는 구조입니다. API Gateway에서 리소스는 어떻게 구성될까요? 모든 API는 루트 리소스(/)로 시작합니다. 여기에 /users, /products처럼 하위 리소스를 추가할 수 있습니다. 더 나아가서 /users/{userId}처럼 경로 파라미터를 포함한 리소스도 만들 수 있습니다. 중괄호 안의 userId는 동적으로 변하는 값입니다. 예를 들어 /users/123, /users/456처럼 실제 사용자 ID가 들어갑니다. 이런 구조를 RESTful 설계라고 부릅니다. 메서드는 어떤 종류가 있을까요? 가장 많이 사용하는 메서드는 네 가지입니다. **GET**은 데이터를 조회할 때, **POST**는 새로운 데이터를 생성할 때, **PUT**은 기존 데이터를 수정할 때, **DELETE**는 데이터를 삭제할 때 사용합니다. 예를 들어 /users 리소스에 GET 메서드를 추가하면 사용자 목록 조회 API가 되고, POST 메서드를 추가하면 새 사용자 등록 API가 됩니다. 하나의 리소스에 여러 메서드를 동시에 추가할 수 있습니다. 위의 코드를 한 줄씩 살펴보겠습니다. 먼저 get-resources 명령으로 API의 루트 리소스 ID를 확인합니다. 모든 리소스는 부모 리소스 ID가 필요하기 때문입니다. 다음으로 create-resource 명령으로 /users 리소스를 생성합니다. parent-id는 루트 리소스의 ID를 넣고, path-part는 실제 경로 이름인 "users"를 입력합니다. 마지막으로 put-method 명령으로 GET 메서드를 추가합니다. authorization-type을 NONE으로 설정하면 인증 없이 누구나 호출할 수 있는 공개 API가 됩니다. 실제 현업에서는 어떻게 활용할까요? 예를 들어 블로그 서비스를 개발한다고 가정해봅시다. /posts 리소스에 GET 메서드를 추가해서 게시글 목록을 조회하고, POST 메서드로 새 게시글을 작성하고, /posts/{postId} 리소스에 PUT 메서드로 게시글을 수정하고, DELETE 메서드로 삭제하는 식입니다. 이런 구조는 직관적이고 이해하기 쉬워서, 프론트엔드 개발자나 외부 파트너가 API 문서를 보고 바로 사용할 수 있습니다. 네이버 블로그, 티스토리 같은 서비스의 API도 이런 RESTful 패턴을 따릅니다. 하지만 주의할 점도 있습니다. 초보 개발자들이 흔히 하는 실수 중 하나는 리소스 이름을 동사로 짓는 것입니다. 예를 들어 /getUsers, /createUser처럼 만드는 경우인데, 이는 REST 원칙에 맞지 않습니다. 리소스는 명사여야 하고, 동작은 메서드로 표현해야 합니다. 따라서 /users 리소스에 GET, POST 메서드를 추가하는 것이 올바른 설계입니다. 또 하나 주의할 점은 경로 파라미터입니다. /users/{userId}처럼 만들 때, 중괄호 안의 이름은 나중에 Lambda 함수에서 그대로 사용됩니다. 따라서 일관된 네이밍을 유지하는 것이 중요합니다. userId, user_id, id 같은 이름이 섞여 있으면 코드가 복잡해집니다. 다시 김개발 씨의 이야기로 돌아가 봅시다. 박시니어 씨의 설명을 들은 김개발 씨는 직접 /users 리소스를 만들고, GET과 POST 메서드를 추가했습니다. "오, 이제 진짜 API처럼 보이네요!" 리소스와 메서드는 API의 뼈대입니다. 이제 이 API를 실제로 Lambda 함수와 연결하고 배포하면 동작하는 API가 됩니다. 여러분도 오늘 배운 내용을 바탕으로 RESTful한 리소스 구조를 설계해보세요. **실전 팁** 💡 - 리소스 이름은 복수형 명사를 사용하세요 (/user가 아니라 /users) - 경로 파라미터 이름은 camelCase나 snake_case 중 하나로 통일하세요 - OPTIONS 메서드는 CORS 설정 시 자동으로 필요하니 미리 추가해두면 좋습니다 --- ## 4. 스테이지 개념 김개발 씨가 API를 만들고 배포하려는데, 화면에 "스테이지 이름을 입력하세요"라는 메시지가 떴습니다. "스테이지가 뭐죠?" 박시니어 씨가 설명했습니다. "개발용, 테스트용, 운영용처럼 환경을 분리하는 거예요." **스테이지**는 API의 배포 환경을 구분하는 개념으로, dev, test, prod처럼 여러 버전을 동시에 관리할 수 있게 해줍니다. 같은 API라도 개발 단계에서는 dev 스테이지로 배포하고, 실제 서비스에는 prod 스테이지로 배포해서 안전하게 운영할 수 있습니다. 각 스테이지는 독립된 URL을 가지며, 설정도 개별적으로 관리됩니다. 다음 코드를 살펴봅시다. ```javascript // 1. API를 dev 스테이지로 배포 aws apigateway create-deployment \ --rest-api-id abc123xyz \ --stage-name dev \ --stage-description "개발 환경" \ --description "첫 배포" // 배포 후 엔드포인트 URL: // https://abc123xyz.execute-api.ap-northeast-2.amazonaws.com/dev/users // 2. 스테이지 설정 확인 aws apigateway get-stage \ --rest-api-id abc123xyz \ --stage-name dev ``` 김개발 씨는 리소스와 메서드까지 모두 만들었습니다. "이제 배포만 하면 되겠다!" 하지만 콘솔 화면에 "스테이지 이름"을 입력하라는 필드가 나타났습니다. "뭘 입력해야 하지?" 박시니어 씨가 웃으며 말했습니다. "스테이지를 모르고 배포하려고 했구나. 그럼 개발 중인 API가 바로 운영 환경에 올라갈 수도 있어요." 그렇다면 **스테이지**는 정확히 무엇일까요? 쉽게 비유하자면, 스테이지는 마치 연극 무대와 같습니다. 같은 연극이라도 리허설 무대, 프리뷰 무대, 정식 공연 무대가 따로 있습니다. 리허설 무대에서는 실수해도 괜찮지만, 정식 공연 무대에서는 완벽해야 합니다. 이처럼 API도 개발 스테이지에서는 자유롭게 테스트하고, 운영 스테이지에서는 안정적으로 서비스하는 방식으로 환경을 분리합니다. 스테이지는 왜 필요할까요? 개발자는 새로운 기능을 만들 때 여러 번 시도하고 실패합니다. 만약 스테이지 없이 모든 변경사항이 바로 운영 환경에 반영된다면, 사용자들이 에러를 겪게 됩니다. 하지만 dev 스테이지에서 충분히 테스트하고, test 스테이지에서 QA를 거친 뒤, 마지막으로 prod 스테이지에 배포하면 안전합니다. 또한 각 스테이지마다 다른 Lambda 함수를 연결하거나, 다른 데이터베이스를 사용할 수도 있습니다. 스테이지는 어떻게 구성될까요? 일반적으로 세 가지 스테이지를 만듭니다. **dev 스테이지**는 개발자가 자유롭게 실험하는 환경입니다. 코드를 수정할 때마다 바로바로 배포해서 확인합니다. **test 스테이지**는 QA 팀이 테스트하는 환경입니다. 기능이 제대로 동작하는지, 엣지 케이스는 없는지 검증합니다. **prod 스테이지**는 실제 사용자가 접근하는 운영 환경입니다. 철저히 검증된 코드만 배포하며, 모니터링과 알람을 설정해서 문제가 생기면 즉시 대응합니다. 위의 코드를 한 줄씩 살펴보겠습니다. create-deployment 명령으로 API를 dev 스테이지에 배포합니다. stage-name에 "dev"를 입력하면, AWS가 자동으로 dev 스테이지를 생성하고 배포합니다. 배포가 완료되면 고유한 URL이 생성되는데, 이 URL에는 API ID와 스테이지 이름이 포함됩니다. 예를 들어 https://abc123xyz.execute-api.ap-northeast-2.amazonaws.com/dev/users처럼 생성됩니다. 이 URL을 브라우저나 Postman에서 호출하면 실제로 API가 동작합니다. 실제 현업에서는 어떻게 활용할까요? 예를 들어 이커머스 플랫폼을 개발하는 팀이 있다고 가정해봅시다. 신규 결제 기능을 추가할 때, 먼저 dev 스테이지에서 개발자가 직접 테스트합니다. 문제가 없으면 test 스테이지에 배포해서 QA 팀이 시나리오 테스트를 진행합니다. 모든 테스트를 통과하면, 마지막으로 prod 스테이지에 배포해서 실제 고객이 사용하게 됩니다. 만약 prod 스테이지에서 문제가 발견되면, 이전 버전의 배포로 즉시 롤백할 수 있습니다. 쿠팡, 11번가 같은 대형 쇼핑몰에서도 이런 다단계 배포 전략을 사용합니다. 하지만 주의할 점도 있습니다. 초보 개발자들이 흔히 하는 실수 중 하나는 모든 스테이지에서 같은 Lambda 함수를 사용하는 것입니다. 이렇게 하면 dev 스테이지에서 테스트하다가 운영 데이터베이스를 건드릴 수 있습니다. 따라서 각 스테이지마다 다른 Lambda 함수 별칭(alias)을 연결하거나, 환경 변수로 데이터베이스 연결 정보를 다르게 설정해야 합니다. 또 하나 주의할 점은 스테이지 변수입니다. 스테이지마다 다른 설정값을 주입할 수 있는데, 예를 들어 dev 스테이지에서는 로깅을 상세하게 남기고, prod 스테이지에서는 에러 로그만 남기는 식으로 활용할 수 있습니다. 이런 변수를 잘 활용하면 코드 수정 없이 환경별 설정을 관리할 수 있습니다. 다시 김개발 씨의 이야기로 돌아가 봅시다. 박시니어 씨의 조언을 듣고, 김개발 씨는 dev 스테이지를 만들어서 먼저 배포했습니다. "아, 이제 안전하게 테스트할 수 있겠네요!" 스테이지는 안전한 배포의 핵심입니다. 개발, 테스트, 운영 환경을 분리해서 관리하면 장애를 예방할 수 있습니다. 여러분도 오늘 배운 내용을 바탕으로 스테이지 전략을 세워보세요. **실전 팁** 💡 - 스테이지 이름은 짧고 명확하게 (dev, test, prod 같은 표준 네이밍 추천) - 각 스테이지마다 다른 Lambda 별칭을 연결해서 환경을 완전히 분리하세요 - 스테이지 변수를 활용하면 환경별 설정을 코드 수정 없이 관리할 수 있습니다 --- ## 5. API 배포하기 김개발 씨가 드디어 API를 완성했습니다. "이제 배포만 하면 되는데, 버튼 하나면 되겠죠?" 박시니어 씨가 고개를 저었습니다. "배포는 신중하게 해야 해요. 한 번 배포하면 URL이 바뀌지 않으니까요." **API 배포**는 작성한 리소스와 메서드를 실제로 사용 가능한 상태로 만드는 과정입니다. 배포하기 전까지는 API가 동작하지 않으며, 배포할 때마다 새로운 배포 버전이 생성됩니다. 스테이지를 선택해서 배포하면 해당 스테이지의 URL로 API에 접근할 수 있게 되고, 배포 히스토리가 자동으로 관리되어 필요할 때 이전 버전으로 롤백할 수 있습니다. 다음 코드를 살펴봅시다. ```javascript // 1. dev 스테이지로 배포 aws apigateway create-deployment \ --rest-api-id abc123xyz \ --stage-name dev \ --description "사용자 조회 기능 추가" // 2. 배포 기록 확인 aws apigateway get-deployments \ --rest-api-id abc123xyz // 3. 특정 배포 ID로 롤백 aws apigateway update-stage \ --rest-api-id abc123xyz \ --stage-name dev \ --patch-operations op=replace,path=/deploymentId,value=deploy123 ``` 김개발 씨는 /users 리소스에 GET 메서드를 추가하고, Lambda 함수도 연결했습니다. "이제 다 됐다!" 하지만 URL을 복사해서 브라우저에 입력했더니 404 에러가 났습니다. "왜 안 되지?" 박시니어 씨가 화면을 보더니 말했습니다. "아, 배포를 안 했네요. API Gateway는 변경사항을 저장하기만 하고, 배포를 해야 실제로 적용돼요." 그렇다면 **API 배포**는 정확히 무엇일까요? 쉽게 비유하자면, API 배포는 마치 책을 출판하는 것과 같습니다. 원고를 아무리 잘 써도, 인쇄하고 서점에 배포하기 전까지는 독자가 읽을 수 없습니다. 이처럼 API도 리소스와 메서드를 아무리 잘 만들어도, 배포하기 전까지는 외부에서 접근할 수 없습니다. 배포 버튼을 누르는 순간, AWS가 모든 설정을 적용하고 URL을 활성화합니다. 배포는 어떤 과정으로 진행될까요? 먼저 배포할 스테이지를 선택합니다. dev 스테이지로 배포할지, prod 스테이지로 배포할지 정하는 것이죠. 다음으로 배포 설명을 입력합니다. "사용자 조회 기능 추가", "버그 수정" 같은 메모를 남기면 나중에 배포 기록을 확인할 때 유용합니다. 마지막으로 배포를 실행하면, AWS가 모든 리소스와 메서드 설정을 스테이지에 반영하고 고유한 배포 ID를 생성합니다. 배포 후에는 무엇이 달라질까요? 배포가 완료되면 스테이지별 URL이 활성화됩니다. 예를 들어 dev 스테이지로 배포했다면, https://abc123xyz.execute-api.ap-northeast-2.amazonaws.com/dev/users 같은 URL이 생성됩니다. 이 URL을 클라이언트에게 전달하면, 브라우저나 모바일 앱에서 바로 API를 호출할 수 있습니다. 또한 배포 히스토리가 자동으로 기록되어, 언제 누가 무엇을 배포했는지 추적할 수 있습니다. 위의 코드를 한 줄씩 살펴보겠습니다. create-deployment 명령으로 dev 스테이지에 배포합니다. description 항목에 "사용자 조회 기능 추가"처럼 의미 있는 메시지를 남기면, 나중에 배포 기록을 볼 때 어떤 변경사항이 포함되었는지 알 수 있습니다. get-deployments 명령으로 배포 기록을 확인할 수 있으며, 각 배포마다 고유한 ID가 부여됩니다. 만약 최신 배포에서 문제가 발생하면, update-stage 명령으로 이전 배포 ID를 지정해서 롤백할 수 있습니다. 실제 현업에서는 어떻게 활용할까요? 예를 들어 배달 앱 서비스를 운영하는 팀이 있다고 가정해봅시다. 신규 쿠폰 기능을 추가할 때, 먼저 dev 스테이지에 배포해서 개발팀이 테스트합니다. 문제가 없으면 test 스테이지에 배포해서 QA 팀이 검증합니다. 모든 테스트를 통과하면 금요일 저녁이 아닌 월요일 오전에 prod 스테이지로 배포합니다. 왜냐하면 만약 문제가 생기면 즉시 대응할 수 있는 시간대가 안전하기 때문입니다. 배달의민족, 쿠팡이츠 같은 서비스에서도 이런 배포 전략을 사용합니다. 하지만 주의할 점도 있습니다. 초보 개발자들이 흔히 하는 실수 중 하나는 배포 설명을 생략하는 것입니다. "배포 1", "배포 2"처럼 의미 없는 메시지만 남기면, 나중에 문제가 생겼을 때 어느 배포가 원인인지 찾기 어렵습니다. 따라서 "결제 API 응답 시간 개선", "로그인 버그 수정"처럼 구체적인 설명을 남기는 습관이 중요합니다. 또 하나 주의할 점은 배포 타이밍입니다. 운영 환경에 배포할 때는 트래픽이 적은 시간대를 선택하는 것이 안전합니다. 만약 점심시간이나 저녁시간처럼 사용자가 많을 때 배포했다가 문제가 생기면, 많은 사용자가 피해를 입습니다. 따라서 새벽 시간이나 이른 아침에 배포하고, 30분 정도 모니터링한 뒤 문제가 없으면 퇴근하는 것이 좋습니다. 다시 김개발 씨의 이야기로 돌아가 봅시다. 박시니어 씨의 조언을 듣고, 김개발 씨는 배포 설명을 "첫 번째 사용자 조회 API 배포"라고 작성하고 dev 스테이지에 배포했습니다. URL을 다시 호출했더니 이번에는 제대로 동작했습니다. "드디어 성공했다!" API 배포는 개발의 마지막 단계입니다. 배포 설명을 잘 작성하고, 적절한 시간에 배포하고, 배포 후 모니터링하는 습관을 들이면 안정적인 서비스를 운영할 수 있습니다. 여러분도 오늘 배운 내용을 바탕으로 첫 배포를 진행해보세요. **실전 팁** 💡 - 배포 설명은 Jira 티켓 번호나 커밋 해시를 포함하면 추적하기 쉽습니다 - 운영 배포는 트래픽이 적은 새벽이나 이른 아침에 진행하세요 - 배포 후 CloudWatch 로그를 30분 정도 모니터링해서 에러가 없는지 확인하세요 --- ## 6. API 키와 사용량 계획 API를 성공적으로 배포한 김개발 씨에게 팀장이 요청했습니다. "외부 파트너사에게 API를 제공하는데, 사용량을 제한할 방법이 있나요?" 김개발 씨가 당황하자, 박시니어 씨가 말했습니다. "API 키와 사용량 계획을 설정하면 돼요." **API 키**는 외부 클라이언트를 식별하는 고유한 문자열로, API 호출 시 헤더에 포함시켜 인증합니다. **사용량 계획**은 API 키별로 호출 횟수를 제한하는 정책으로, 초당 요청 수와 일일 최대 호출 수를 설정할 수 있습니다. 예를 들어 무료 플랜은 하루 1000건, 유료 플랜은 하루 10000건처럼 차등 제한을 두면, 과도한 트래픽을 방지하고 수익 모델을 만들 수 있습니다. 다음 코드를 살펴봅시다. ```javascript // 1. 사용량 계획 생성 aws apigateway create-usage-plan \ --name "BasicPlan" \ --description "무료 사용자 플랜" \ --throttle rateLimit=10,burstLimit=20 \ --quota limit=1000,period=DAY // 2. API 키 생성 aws apigateway create-api-key \ --name "PartnerA-Key" \ --description "파트너사 A의 API 키" \ --enabled // 3. API 키를 사용량 계획에 연결 aws apigateway create-usage-plan-key \ --usage-plan-id plan123 \ --key-id key456 \ --key-type API_KEY ``` 김개발 씨는 API를 성공적으로 배포했고, 사내 프론트엔드 팀이 잘 사용하고 있습니다. 그런데 팀장이 새로운 요청을 했습니다. "외부 파트너사 세 곳에 API를 제공하려고 하는데, 각 파트너마다 사용량을 다르게 제한할 수 있나요?" 김개발 씨는 당황했습니다. "어떻게 그걸 구분하지?" 박시니어 씨가 화이트보드에 그림을 그리며 설명했습니다. "API 키로 파트너를 구분하고, 사용량 계획으로 제한을 걸면 돼요." 그렇다면 **API 키**와 **사용량 계획**은 정확히 무엇일까요? 쉽게 비유하자면, API 키는 마치 회원 카드와 같습니다. 스타벅스에 가면 일반 회원, 골드 회원, VIP 회원처럼 등급이 있고, 각 등급마다 혜택이 다릅니다. API 키도 마찬가지입니다. 파트너 A는 하루 1000건, 파트너 B는 하루 5000건처럼 각각 다른 사용량 제한을 받습니다. 사용량 계획은 이런 등급별 정책을 정의하는 것입니다. API 키는 왜 필요할까요? 만약 API가 공개되어 있고 제한이 없다면, 누군가 악의적으로 수백만 건의 요청을 보낼 수 있습니다. 그러면 Lambda 함수 비용이 폭증하고, 정상 사용자들은 느린 응답을 겪게 됩니다. API 키를 사용하면 등록된 파트너만 접근할 수 있고, 파트너별로 사용량을 추적할 수 있습니다. 또한 특정 파트너가 약정한 호출 수를 초과하면 자동으로 차단할 수 있습니다. 사용량 계획은 어떻게 구성될까요? 사용량 계획에는 세 가지 주요 설정이 있습니다. **Rate Limit**은 초당 평균 요청 수입니다. 예를 들어 10으로 설정하면, 1초에 평균 10건의 요청만 허용합니다. **Burst Limit**은 짧은 시간에 허용되는 최대 요청 수입니다. 20으로 설정하면, 순간적으로 20건까지는 허용하지만 그 이상은 거부합니다. **Quota**는 일일 또는 월별 총 요청 수입니다. 1000으로 설정하면, 하루에 1000건을 초과하는 순간부터 요청이 차단됩니다. 위의 코드를 한 줄씩 살펴보겠습니다. 먼저 create-usage-plan 명령으로 "BasicPlan"이라는 무료 사용자 플랜을 만듭니다. throttle 옵션에서 rateLimit=10은 초당 평균 10건, burstLimit=20은 순간 최대 20건을 의미합니다. quota 옵션에서 limit=1000은 하루 최대 1000건, period=DAY는 일일 제한을 의미합니다. 다음으로 create-api-key 명령으로 "PartnerA-Key"라는 API 키를 생성합니다. 마지막으로 create-usage-plan-key 명령으로 이 API 키를 BasicPlan에 연결하면, 파트너 A가 API를 호출할 때 자동으로 제한이 적용됩니다. 실제 현업에서는 어떻게 활용할까요? 예를 들어 날씨 정보 API를 제공하는 스타트업이 있다고 가정해봅시다. 무료 플랜은 하루 100건, 기본 플랜은 하루 1000건, 프리미엄 플랜은 하루 10000건으로 차등 제한을 둡니다. 각 고객사에게 API 키를 발급할 때, 플랜에 따라 다른 사용량 계획을 연결합니다. 고객이 한도를 초과하면 자동으로 429 에러(Too Many Requests)가 반환되고, 업그레이드를 유도할 수 있습니다. 네이버 클라우드, 카카오 개발자센터에서도 이런 방식으로 API를 제공합니다. 하지만 주의할 점도 있습니다. 초보 개발자들이 흔히 하는 실수 중 하나는 API 키를 코드에 하드코딩하는 것입니다. 예를 들어 프론트엔드 JavaScript 파일에 API 키를 직접 넣으면, 누구나 브라우저 개발자 도구로 볼 수 있습니다. 따라서 API 키는 반드시 서버 사이드에서 관리하고, 클라이언트에는 노출하지 않아야 합니다. 프론트엔드에서 API를 호출할 때는 백엔드 서버를 경유하도록 설계하는 것이 안전합니다. 또 하나 주의할 점은 사용량 계획의 기간입니다. DAY, WEEK, MONTH 중 하나를 선택할 수 있는데, 고객의 사용 패턴을 고려해야 합니다. 예를 들어 월 초에 트래픽이 몰리는 서비스라면, 일일 제한보다 월간 제한이 더 적합할 수 있습니다. 반대로 트래픽이 일정한 서비스라면, 일일 제한으로 세밀하게 관리하는 것이 좋습니다. 다시 김개발 씨의 이야기로 돌아가 봅시다. 박시니어 씨의 조언을 듣고, 김개발 씨는 파트너사별로 API 키를 발급하고 사용량 계획을 연결했습니다. 팀장이 만족스러워하며 말했습니다. "이제 안심하고 외부에 API를 제공할 수 있겠네요!" API 키와 사용량 계획은 API를 상품화하는 핵심 기능입니다. 무료 플랜과 유료 플랜을 구분하고, 악의적인 트래픽을 차단하고, 수익 모델을 만들 수 있습니다. 여러분도 오늘 배운 내용을 바탕으로 API 비즈니스 모델을 설계해보세요. **실전 팁** 💡 - API 키는 절대 클라이언트 코드에 하드코딩하지 마세요 (서버에서만 사용) - 사용량 계획은 무료, 기본, 프리미엄처럼 3단계 정도로 구분하면 관리하기 쉽습니다 - CloudWatch에서 API 키별 사용량을 모니터링해서 업그레이드 시점을 파악하세요 --- 이상으로 학습을 마칩니다. 위 내용을 직접 코드로 작성해보면서 익혀보세요!

카테고리: AWS

언어: JavaScript

태그: AWS, APIGateway, REST, Lambda, CloudService

작성자: AI Generated

프리미엄 콘텐츠 - 3개월 무료 체험 가능

CodeDeck

AWS API Gateway REST API 완벽 가이드

목차

1. API Gateway란?

2. REST API 생성

3. 리소스와 메서드

4. 스테이지 개념

5. API 배포하기

6. API 키와 사용량 계획

댓글 (0)

함께 보면 좋은 카드 뉴스

서비스 메시 완벽 가이드

EFK 스택 로깅 완벽 가이드

Grafana 대시보드 완벽 가이드

분산 추적 완벽 가이드

마이크로서비스 통합 완벽 가이드