목차
서론: API, 왜 알아야 하는가?
노코드 자동화의 세계에서 API(Application Programming Interface)는 마법의 문과 같습니다. Make나 Zapier가 수천 개의 앱을 연결할 수 있는 것은 바로 이 API 덕분입니다. 공식 연동 모듈이 있는 서비스는 버튼 클릭만으로 연결되지만, 세상에는 그보다 훨씬 많은 서비스가 있습니다. API의 기본 원리를 이해하면 공식 모듈이 없는 서비스도 자유롭게 연결할 수 있고, 기존 모듈의 한계를 넘어서는 고급 기능도 활용할 수 있습니다.
이 글에서는 API의 기본 개념부터 시작하여, HTTP 요청의 구조, 인증 방식, 실제 Make에서의 구현까지 단계별로 상세히 설명합니다. 프로그래밍 경험이 전혀 없어도 이해할 수 있도록 쉽게 풀어 설명하겠습니다.
1장: API 기본 개념
1.1 API란 무엇인가?
API는 Application Programming Interface의 약자로, 두 소프트웨어가 서로 통신하는 방법을 정의한 규약입니다. 쉽게 말해 “요청하면 응답하는” 약속된 규칙입니다.
일상생활의 예로 설명하면, 레스토랑에서 식사를 한다고 상상해보세요. 당신(클라이언트)은 메뉴판을 보고 주문합니다. 웨이터(API)가 주문을 받아 주방(서버)에 전달합니다. 주방에서 음식(데이터)을 만들어 웨이터를 통해 당신에게 전달합니다.
API도 똑같습니다. 당신의 앱(클라이언트)이 다른 서비스(서버)에 데이터를 요청합니다. API가 그 요청을 전달합니다. 서버가 처리한 결과를 API를 통해 반환합니다.
중요한 점은 당신이 주방에 직접 들어가지 않아도 음식을 받을 수 있다는 것입니다. API도 마찬가지로, 서버 내부가 어떻게 작동하는지 몰라도 정해진 규칙(API)만 따르면 원하는 결과를 얻을 수 있습니다.
1.2 REST API 이해하기
현대 웹에서 가장 널리 사용되는 API 스타일은 REST(Representational State Transfer)입니다. REST API의 핵심 원칙을 이해하면 대부분의 API를 사용할 수 있습니다.
리소스(Resource)는 API가 다루는 데이터의 단위입니다. 사용자(users), 주문(orders), 제품(products) 등이 리소스입니다. 각 리소스는 고유한 URL(엔드포인트)로 식별됩니다. 예를 들어 https://api.example.com/users는 사용자 리소스이고, https://api.example.com/users/123은 ID가 123인 특정 사용자입니다.
HTTP 메서드는 리소스에 대해 어떤 작업을 할지 지정합니다. GET은 데이터를 조회합니다. 읽기 전용이며 서버 데이터를 변경하지 않습니다. POST는 새 데이터를 생성합니다. 새 사용자 등록, 새 주문 생성 등에 사용합니다. PUT은 기존 데이터를 전체 교체합니다. 리소스의 모든 필드를 업데이트합니다. PATCH는 기존 데이터를 부분 수정합니다. 특정 필드만 업데이트합니다. DELETE는 데이터를 삭제합니다.
상태 코드(Status Code)는 요청의 결과를 숫자로 나타냅니다. 200 OK는 요청 성공입니다. 201 Created는 새 리소스 생성 성공입니다. 400 Bad Request는 잘못된 요청입니다(파라미터 오류 등). 401 Unauthorized는 인증 필요합니다. 403 Forbidden은 권한 없음입니다. 404 Not Found는 리소스를 찾을 수 없음입니다. 500 Internal Server Error는 서버 오류입니다.
1.3 HTTP 요청의 구조
HTTP 요청은 여러 구성요소로 이루어집니다. 각 부분의 역할을 이해하면 API 문서를 읽고 요청을 구성할 수 있습니다.
URL(Endpoint)은 요청을 보낼 주소입니다. 기본 URL(Base URL)은 API의 기본 주소입니다. 예를 들어 https://api.example.com 같은 형식입니다. 경로(Path)는 특정 리소스를 지정합니다. 예를 들어 /users, /orders/123 같은 형식입니다. 쿼리 파라미터(Query Parameters)는 추가 옵션을 지정합니다. ? 뒤에 key=value 형태로 붙습니다. 예를 들어 ?status=active&limit=10 같은 형식입니다.
헤더(Headers)는 요청에 대한 메타 정보입니다. Content-Type은 보내는 데이터의 형식입니다. JSON이면 application/json, 폼 데이터면 application/x-www-form-urlencoded입니다. Authorization은 인증 정보입니다. API 키나 토큰을 여기에 넣습니다. Accept는 원하는 응답 형식입니다. 대부분 application/json입니다. User-Agent는 요청을 보내는 클라이언트 정보입니다.
본문(Body)은 POST, PUT, PATCH 요청 시 서버로 보내는 데이터입니다. 대부분 JSON 형식으로 작성합니다. 예를 들어 새 사용자 생성 시의 Body는 {“name”: “홍길동”, “email”: “hong@example.com”, “age”: 30} 같은 형식입니다.
2장: API 인증 완벽 가이드
2.1 인증이 필요한 이유
대부분의 API는 인증을 요구합니다. 누가 요청하는지 확인하여 권한을 관리하고, 악의적인 사용을 방지합니다. 인증 방식은 API마다 다르므로, 문서를 확인하여 해당 API가 어떤 인증 방식을 사용하는지 파악해야 합니다.
2.2 API Key 인증
가장 단순한 인증 방식입니다. 서비스에 가입하면 고유한 API Key(문자열)를 발급받습니다. 이 키를 요청에 포함시켜 보냅니다.
API Key를 포함시키는 방법은 API마다 다릅니다. 헤더에 포함하는 방식으로 X-API-Key: your_api_key_here 또는 Authorization: ApiKey your_api_key_here를 사용합니다. 쿼리 파라미터에 포함하는 방식은 https://api.example.com/data?api_key=your_api_key_here 형태입니다.
어떤 방식인지는 API 문서에 명시되어 있습니다. “Authentication” 또는 “Authorization” 섹션을 찾아보세요.
API Key 사용 시 주의사항으로, API Key는 비밀번호와 같습니다. 절대 공개적인 곳(GitHub 등)에 노출하지 마세요. Make에서는 연결(Connection) 설정에 저장하면 안전하게 관리됩니다. 주기적으로 키를 재발급하고 이전 키는 폐기하는 것이 좋습니다.
2.3 Bearer Token 인증
OAuth 2.0에서 주로 사용하는 방식입니다. 로그인 과정을 통해 액세스 토큰(Access Token)을 발급받습니다. 이 토큰을 Authorization 헤더에 포함시켜 요청합니다.
헤더 형식은 Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…입니다.
“Bearer”는 토큰 타입을 나타내는 키워드입니다. 그 뒤에 공백 하나, 그리고 실제 토큰이 옵니다.
토큰 발급 방식은 서비스마다 다릅니다. 어떤 서비스는 대시보드에서 직접 토큰을 발급합니다. 어떤 서비스는 OAuth 플로우를 통해 토큰을 얻습니다. 토큰에는 만료 시간이 있을 수 있습니다. 만료되면 재발급이 필요합니다.
2.4 OAuth 2.0 상세 설명
OAuth 2.0은 복잡하지만 가장 안전한 인증 방식입니다. 사용자가 비밀번호를 제3자 앱에 직접 알려주지 않고도 권한을 부여할 수 있습니다.
OAuth 2.0 플로우(Authorization Code Grant)를 단계별로 살펴보면, 1단계 인증 요청에서 사용자가 “Google로 로그인” 버튼을 클릭합니다. 앱은 사용자를 Google 인증 페이지로 리다이렉트합니다. URL에는 client_id, redirect_uri, scope, response_type=code가 포함됩니다.
2단계 사용자 동의에서 사용자가 Google에 로그인합니다. “이 앱이 다음 권한을 요청합니다” 화면이 표시됩니다. 사용자가 “허용”을 클릭합니다.
3단계 인증 코드 수신에서 Google이 사용자를 redirect_uri로 돌려보냅니다. URL에 인증 코드(code)가 포함됩니다. 예: https://yourapp.com/callback?code=abc123
4단계 토큰 교환에서 앱이 인증 코드를 Google 토큰 엔드포인트로 보냅니다. client_id, client_secret, code, redirect_uri를 포함합니다. Google이 액세스 토큰(access_token)을 반환합니다.
5단계 API 호출에서 이제 액세스 토큰을 사용하여 Google API를 호출할 수 있습니다. Authorization: Bearer {access_token}
Make에서의 OAuth 처리를 보면, 다행히 Make는 OAuth 2.0을 자동으로 처리합니다. 공식 모듈(Gmail, Google Sheets 등)을 사용할 때 “Add connection”을 클릭하면 OAuth 플로우가 자동으로 진행됩니다. 사용자는 로그인하고 권한을 승인하기만 하면 됩니다.
커스텀 OAuth가 필요한 경우, Make의 “OAuth 2.0” 연결 유형을 사용합니다. Authorize URL, Token URL, Client ID, Client Secret, Scope 등을 설정합니다. 서비스의 OAuth 문서를 참조하여 각 값을 입력합니다.
2.5 Basic 인증
가장 오래된 인증 방식 중 하나입니다. 사용자명과 비밀번호를 Base64로 인코딩하여 전송합니다.
형식은 Authorization: Basic base64(username:password)입니다. 예를 들어, 사용자명이 “user”이고 비밀번호가 “pass”이면 user:pass를 Base64 인코딩한 dXNlcjpwYXNz를 사용합니다. 최종 헤더는 Authorization: Basic dXNlcjpwYXNz입니다.
Make에서는 HTTP 모듈 중 “Make a Basic Auth request”를 사용하면 자동으로 처리됩니다. Username과 Password 필드에 값을 입력하면 됩니다.
3장: Make에서 HTTP 모듈 활용하기
3.1 HTTP 모듈 종류와 선택
Make의 HTTP 모듈은 어떤 API든 호출할 수 있는 범용 도구입니다.
Make a request는 가장 범용적인 모듈입니다. 모든 HTTP 메서드, 헤더, 바디를 자유롭게 설정합니다. 대부분의 API 호출에 사용합니다.
Make a Basic Auth request는 Basic 인증이 필요한 API용입니다. Username/Password를 입력하면 자동으로 인증 헤더를 생성합니다.
Make an OAuth 2.0 request는 OAuth 2.0 인증이 필요한 API용입니다. 토큰 갱신을 자동으로 처리합니다.
Get a file은 파일(이미지, PDF 등)을 다운로드합니다. 바이너리 데이터를 처리할 수 있습니다.
일반적인 API 호출에는 Make a request를 사용하세요. 인증이 필요하면 헤더에 직접 추가하거나, 해당 인증 방식의 전용 모듈을 사용하세요.
3.2 Make a request 상세 설정
실제 API 호출을 위해 Make a request 모듈의 각 설정을 살펴봅시다.
URL 필드에 API 엔드포인트 전체 주소를 입력합니다. 이전 모듈의 데이터를 매핑할 수 있습니다. 예: https://api.openai.com/v1/chat/completions
Method에서 HTTP 메서드를 선택합니다. GET, POST, PUT, PATCH, DELETE 등 중에서 API 문서에 명시된 메서드를 선택합니다.
Headers는 요청 헤더를 추가합니다. “Add header” 버튼으로 필요한 만큼 추가합니다. 일반적인 헤더로는 Authorization(인증 토큰), Content-Type(보통 application/json), Accept(보통 application/json)가 있습니다.
Query String은 URL 파라미터를 구조화하여 추가합니다. URL에 직접 ?key=value로 넣어도 되지만, 여기서 관리하면 더 깔끔합니다.
Body type에서 POST, PUT, PATCH 요청 시 선택합니다. Raw는 JSON, XML 등 텍스트 데이터입니다. Multipart/form-data는 파일 업로드나 복합 데이터입니다. Application/x-www-form-urlencoded는 폼 제출 형식입니다. 대부분의 REST API는 Raw(JSON)를 사용합니다.
Request content에서 Body type이 Raw일 때 실제 데이터를 입력합니다. JSON 형식으로 작성합니다. 이전 모듈의 데이터를 매핑할 수 있습니다.
Parse response를 Yes로 설정하면 JSON 응답을 자동으로 파싱합니다. 파싱된 데이터는 다음 모듈에서 바로 매핑할 수 있습니다. 대부분의 경우 Yes로 설정합니다.
3.3 실전 예제: OpenAI API 호출
실제 API 호출 예제로 OpenAI의 Chat Completions API를 호출해봅시다.
사전 준비로 OpenAI 계정을 만들고 platform.openai.com에서 API 키를 발급합니다.
Make 설정을 보면, URL은 https://api.openai.com/v1/chat/completions입니다. Method는 POST입니다. Headers에는 Authorization: Bearer sk-your-api-key-here와 Content-Type: application/json을 추가합니다. Body type은 Raw입니다. Request content는 다음과 같습니다:
{“model”: “gpt-3.5-turbo”, “messages”: [{“role”: “system”, “content”: “You are a helpful assistant.”}, {“role”: “user”, “content”: “안녕하세요, 오늘 날씨 어때요?”}], “max_tokens”: 500}
Parse response는 Yes로 설정합니다.
응답 구조를 보면, 성공 시 다음과 같은 JSON이 반환됩니다:
{“id”: “chatcmpl-xxx”, “object”: “chat.completion”, “created”: 1234567890, “model”: “gpt-3.5-turbo”, “choices”: [{“index”: 0, “message”: {“role”: “assistant”, “content”: “안녕하세요! 저는 AI 어시스턴트라 실제 날씨 정보는 알 수 없지만…”}, “finish_reason”: “stop”}], “usage”: {“prompt_tokens”: 30, “completion_tokens”: 50, “total_tokens”: 80}}
응답 활용은 Parse response를 Yes로 설정했으므로, 다음 모듈에서 choices[0].message.content로 AI 응답 텍스트에 접근할 수 있습니다.
3.4 실전 예제: 날씨 API 호출
무료 날씨 API인 OpenWeatherMap을 호출해봅시다.
사전 준비로 openweathermap.org에서 무료 계정을 만들고 API 키를 발급합니다.
Make 설정을 보면, URL은 https://api.openweathermap.org/data/2.5/weather입니다. Method는 GET입니다. Query String에는 q: Seoul (도시명), appid: your-api-key (API 키), units: metric (섭씨 온도), lang: kr (한국어 응답)을 추가합니다. Parse response는 Yes로 설정합니다.
응답 구조는 다음과 같습니다:
{“coord”: {“lon”: 126.9778, “lat”: 37.5683}, “weather”: [{“id”: 800, “main”: “Clear”, “description”: “맑음”, “icon”: “01d”}], “main”: {“temp”: 15.3, “feels_like”: 14.2, “temp_min”: 13.0, “temp_max”: 17.0, “humidity”: 45}, “name”: “Seoul”}
활용 예시로 슬랙에 날씨를 알리는 메시지는 다음과 같이 작성할 수 있습니다: “오늘 서울 날씨: main.temp°C, weather[0].description”
4장: API 문서 읽는 법
4.1 API 문서의 구조
처음 보는 API를 사용하려면 문서를 읽어야 합니다. API 문서는 보통 비슷한 구조를 가지고 있습니다.
Overview/Introduction은 API의 목적, 기본 URL, 버전 정보 등을 설명합니다.
Authentication은 인증 방식을 설명합니다. API 키를 어디서 발급받는지, 어떻게 요청에 포함시키는지 안내합니다.
Endpoints/Resources는 사용 가능한 모든 API 엔드포인트 목록입니다. 각 엔드포인트의 URL, 메서드, 파라미터, 응답 형식을 설명합니다.
Request/Response Examples는 실제 요청과 응답 예시입니다. 복사해서 바로 테스트해볼 수 있습니다.
Error Codes는 발생 가능한 에러 코드와 의미를 설명합니다.
Rate Limits는 시간당 호출 횟수 제한을 설명합니다.
4.2 엔드포인트 문서 읽기
특정 엔드포인트의 문서를 읽는 방법을 예시로 살펴봅시다. 예: “Create a new user” 엔드포인트
POST /users라는 표시에서 POST는 HTTP 메서드, /users는 경로입니다. 실제 URL은 기본 URL + 경로입니다. 예: https://api.example.com/users
Headers 섹션에서 필수 헤더를 확인합니다. Authorization: Bearer {token}은 (Required)로 표시됩니다. Content-Type: application/json도 필요합니다.
Request Body 섹션에서 보내야 할 데이터의 구조를 확인합니다. name(string, required)은 사용자 이름입니다. email(string, required)은 이메일 주소입니다. age(integer, optional)는 나이로 선택사항입니다.
Response 섹션에서 200 Created의 예시 응답을 확인합니다: {“id”: 123, “name”: “홍길동”, “email”: “hong@example.com”, “created_at”: “2024-01-15T10:30:00Z”}
Error Responses에서 400 Bad Request는 필수 필드 누락, 401 Unauthorized는 인증 실패, 409 Conflict는 이미 존재하는 이메일입니다.
4.3 API 테스트 도구 활용
Make에서 바로 시도하기 전에, API 테스트 도구로 먼저 확인하면 좋습니다.
Postman은 가장 인기 있는 API 테스트 도구입니다. GUI로 요청을 쉽게 구성할 수 있습니다. 요청/응답 히스토리 저장이 됩니다. 컬렉션으로 API를 정리할 수 있습니다.
Insomnia는 Postman의 대안으로 더 가벼운 인터페이스입니다.
curl은 명령줄 도구입니다. API 문서에 curl 예시가 많이 제공됩니다.
API 문서의 “Try it” 기능을 활용할 수도 있습니다. 많은 API 문서가 브라우저에서 바로 테스트할 수 있는 기능을 제공합니다.
테스트 순서로는, 1) API 문서의 예시를 그대로 복사하여 테스트합니다. 2) 성공하면 파라미터를 하나씩 변경해봅니다. 3) 원하는 동작이 확인되면 Make에서 구현합니다.
5장: 고급 API 활용 기법
5.1 페이지네이션 처리
API가 대량의 데이터를 반환할 때는 한 번에 모든 데이터를 주지 않습니다. 대신 페이지 단위로 나누어 제공합니다. 이를 페이지네이션(Pagination)이라고 합니다.
Offset 기반 페이지네이션의 요청 예시는 GET /users?limit=100&offset=0이고, 응답에는 total과 함께 데이터가 포함됩니다. 다음 페이지는 offset=100으로 요청합니다.
Cursor 기반 페이지네이션의 요청은 GET /users?limit=100이고, 응답에는 next_cursor가 포함됩니다. 다음 페이지는 cursor=xxx로 요청합니다.
Make에서 페이지네이션을 처리하려면 반복(Loop) 구조가 필요합니다. 간단한 방법으로는 HTTP 모듈의 “Pagination” 설정을 사용합니다(지원하는 경우). 또는 “Repeater” 모듈과 조합하여 수동으로 구현합니다.
5.2 Rate Limiting 대응
대부분의 API는 호출 횟수 제한이 있습니다. 예를 들어 “분당 60회”, “일당 1,000회” 같은 제한입니다. 제한을 초과하면 429 Too Many Requests 에러가 발생합니다.
대응 전략으로, 첫째 호출 간격 조절이 있습니다. Make의 Sleep 모듈로 요청 사이에 지연을 추가합니다. 예: 분당 60회 제한이면 1초 간격으로 호출합니다.
둘째, 배치 처리가 있습니다. 가능하면 개별 호출 대신 배치 API를 사용합니다. 예: 사용자 100명 조회 시 100번 호출 대신 한 번에 조회합니다.
셋째, 에러 처리가 있습니다. 429 에러 발생 시 Error Handler에서 잠시 대기 후 재시도합니다. 응답 헤더의 Retry-After 값을 참조합니다.
넷째, 캐싱이 있습니다. 자주 조회하는 정적 데이터는 Data Store에 캐싱합니다. 매번 API를 호출하지 않고 캐시된 데이터를 사용합니다.
5.3 Webhook 활용
지금까지는 Make에서 외부 API를 “호출”하는 방식을 다뤘습니다. 반대로, 외부 서비스가 Make를 호출하도록 할 수도 있습니다. 이를 Webhook이라고 합니다.
Webhook의 장점은 실시간성입니다. 폴링 방식은 주기적으로 확인하므로 지연이 있습니다. Webhook은 이벤트 발생 즉시 알려줍니다. 또한 효율성 측면에서 불필요한 API 호출이 없습니다. 변화가 있을 때만 호출됩니다.
Make에서 Webhook 설정 방법은, Webhook 모듈 “Custom webhook”을 시나리오에 추가합니다. 고유한 Webhook URL이 생성됩니다. 이 URL을 외부 서비스에 등록합니다. 외부 서비스에서 이벤트가 발생하면 해당 URL로 데이터를 전송합니다. Make 시나리오가 즉시 트리거됩니다.
Webhook을 지원하는 서비스의 예로는 Stripe, GitHub, Shopify, Slack, Twilio 등이 있습니다. 대부분의 현대적인 서비스는 Webhook을 제공합니다.
6장: 에러 처리와 디버깅
6.1 일반적인 API 에러와 해결
401 Unauthorized는 인증에 실패한 경우입니다. API 키나 토큰이 올바른지 확인합니다. 토큰이 만료되지 않았는지 확인합니다. 헤더 이름이 정확한지 확인합니다(Authorization vs X-API-Key).
400 Bad Request는 요청 형식이 잘못된 경우입니다. JSON 문법이 올바른지 확인합니다(쉼표, 따옴표 등). 필수 필드가 모두 포함되었는지 확인합니다. 데이터 타입이 맞는지 확인합니다(문자열 vs 숫자).
404 Not Found는 엔드포인트나 리소스를 찾을 수 없는 경우입니다. URL이 정확한지 확인합니다. API 버전이 맞는지 확인합니다(v1 vs v2). 리소스 ID가 실제로 존재하는지 확인합니다.
403 Forbidden은 권한이 없는 경우입니다. API 키의 권한 범위(scope)를 확인합니다. 해당 작업에 필요한 플랜인지 확인합니다.
500 Internal Server Error는 서버 측 문제입니다. 잠시 후 재시도합니다. 지속되면 서비스 상태 페이지를 확인합니다.
6.2 디버깅 팁
Make의 실행 기록을 활용합니다. 각 모듈의 입력/출력을 확인할 수 있습니다. 어느 단계에서 문제가 발생했는지 파악합니다.
단계별로 테스트합니다. 복잡한 시나리오는 한 번에 전체를 테스트하지 말고, 모듈 하나씩 추가하며 테스트합니다.
API 응답 전체를 확인합니다. Parse response를 No로 설정하면 원시 응답을 볼 수 있습니다. 예상과 다른 응답 구조일 수 있습니다.
API 문서와 대조합니다. 실제 응답과 문서의 예시를 비교합니다. 버전에 따라 응답 구조가 다를 수 있습니다.
결론
API는 처음에는 복잡해 보이지만, 기본 원리를 이해하면 어떤 API든 사용할 수 있습니다. 이 글에서 다룬 내용을 요약하면, API는 표준화된 요청-응답 규약입니다. REST API는 URL, HTTP 메서드, 헤더, 바디로 구성됩니다. 인증 방식을 파악하고 올바르게 적용해야 합니다. Make의 HTTP 모듈로 어떤 API든 호출할 수 있습니다. API 문서를 읽고 테스트하는 습관이 중요합니다.
지금 바로 관심 있는 서비스의 API 문서를 찾아보세요. OpenAI, 날씨 API, 환율 API 등 무료로 사용할 수 있는 API로 연습해보세요. 실습을 통해 자신감을 키우면 어떤 API도 두렵지 않게 됩니다.
