api 뜻 | 호출 순서와 오류 코드까지 쉽게 이해하는 법

api 뜻은 서로 다른 프로그램이 정해진 규칙으로 기능과 데이터를 요청하고 응답받는 연결 통로예요.
웹에서는 클라이언트가 서버에 HTTP 요청을 보내고, 서버가 HTTP 응답을 돌려주는 방식으로 움직입니다.

api 뜻, 프로그램끼리 대화하는 약속이에요

API는 서로 다른 소프트웨어가 정해진 규칙으로 기능이나 데이터를 요청하고 응답받도록 만든 인터페이스예요.
Google Cloud도 Cloud API를 애플리케이션을 통합하기 위한 프로그래밍 인터페이스로 설명합니다.

식당에서 손님은 주방에 들어가지 않고 주문서를 점원에게 건네요. 점원이 주방에 전하고 음식을 가져다주죠. 여기서 점원과 주문서 양식이 API 역할을 해요. 주방 안이 어떻게 돌아가는지 몰라도 정해진 방식으로 주문하면 결과를 받습니다.

그래서 앱이 날씨를 보여 주거나 지도를 띄울 때, 직접 데이터를 만들지 않고 다른 서비스의 API를 불러 쓰는 경우가 많아요.
AI 챗봇도 같은 방식으로 다른 프로그램에 연결되는데, 먼저 써 보고 싶다면 chatgpt 무료로 쓰는 방법부터 확인해 보세요.

API 호출 순서, 요청 보내고 응답 읽으면 끝이에요

웹 API의 기본 흐름은 클라이언트가 서버에 요청을 보내고 서버가 응답을 돌려주는 거예요.
요청에는 보통 메서드, 대상 URI, 헤더가 들어가고, 필요할 때 요청 본문을 함께 보냅니다.

대상 주소(URI) 정하기어떤 리소스를 다룰지 주소로 정해요. URI가 요청 대상을 가리킵니다.

메서드 고르기조회인지 등록인지 수정인지에 맞춰 GET, POST 같은 메서드를 골라요.

헤더와 본문 채우기인증 정보 같은 헤더를 붙이고, 보낼 데이터가 있으면 본문에 담아요.

응답 읽기상태 코드를 먼저 보고, 성공이면 응답 본문의 데이터를 꺼내 써요.

예시 1 · 날씨 앱을 만드는 민수 씨민수 씨가 날씨 서비스 API에 서울 날씨를 달라고 요청한다고 가정해 볼게요.
조회라서 GET을 고르고 지역 값을 주소에 담아 보내면, 서버가 200 상태 코드와 함께 날씨 데이터를 돌려줍니다.

GET POST PUT PATCH DELETE 차이, 하는 일이 달라요

메서드는 요청의 목적과 기대하는 성공 결과를 나타내요.
GET은 리소스를 조회하고, 일반적으로 요청 본문을 포함하지 않습니다.

멱등은 같은 요청을 여러 번 보내도 결과가 한 번 보낸 것과 같다는 뜻이에요. 엘리베이터 5층 버튼을 두 번 눌러도 5층에 가는 건 똑같죠. 그래서 네트워크가 끊겨 다시 보내야 할 때 PUT과 DELETE는 비교적 안심하고 재시도할 수 있어요.

HTTP 표준에서 GET, HEAD, OPTIONS, TRACE는 안전 메서드로 정의돼요.
HEAD는 GET과 같은 응답 정보를 본문 없이 받고, OPTIONS는 대상이 지원하는 통신 옵션을 알려 줍니다.

API 오류 코드, 첫 숫자만 봐도 절반은 풀려요

HTTP 상태 코드는 100부터 599 사이의 3자리 정수예요.
첫 숫자가 1xx 정보, 2xx 성공, 3xx 리다이렉션, 4xx 클라이언트 오류, 5xx 서버 오류를 뜻합니다.

2xx 성공200은 성공, 201은 생성 성공, 204는 돌려줄 본문이 없는 성공이에요.

4xx 요청 쪽 문제400 잘못된 요청, 401 인증 필요 또는 실패, 403 서버가 요청 거부, 404 대상 없음, 405 메서드 미지원, 429 요청 한도 초과예요.

5xx 서버 쪽 문제500 일반 서버 오류, 502 게이트웨이가 잘못된 응답을 받음, 503 일시적으로 처리할 준비가 안 된 상태예요.

예시 2 · 오류율을 계산해 보는 서연 씨서연 씨의 앱이 하루에 API를 1,000번 호출했고, 4xx와 5xx 응답이 20번 나왔다고 가정해 볼게요.
오류율은 20 ÷ 1,000 × 100 = 2%이고, 성공은 980번이라 성공률은 98%예요. 실제 서비스는 성공 기준과 집계 범위가 다를 수 있어 해당 서비스 문서를 함께 봐야 합니다.

4xx는 보낸 쪽의 요청을 고쳐야 하고, 5xx는 서버 쪽 문제일 가능성이 커요. 같은 오류인데 코드가 다르면 원인도 다르니 숫자를 꼭 확인하세요.

API 키 사용법, 신분증이 아니라 출입 번호표예요

API 키는 호출한 프로젝트를 식별해서 과금과 할당량에 연결할 수 있어요.
다만 Google Cloud의 표준 API 키는 호출 주체를 인증하지는 않습니다.

API 키는 놀이공원 입장권 번호와 비슷해요. 어느 단체가 들어왔는지는 알려 주지만, 입장한 사람이 누구인지까지 증명하지는 않아요. 사람의 권한을 확인해야 하는 서비스는 OAuth 같은 별도 인증을 함께 씁니다.

OAuth 클라이언트 ID는 최종 사용자가 가진 리소스에 접근하는 애플리케이션을 식별하는 데 쓰는 인증 자격 증명이에요.
AI 서비스를 유료로 쓸 생각이라면 클로드 요금제 글에서 요금제 구성을 먼저 볼 수 있어요.

API 키, 토큰, 비밀번호는 공개 저장소, 프런트엔드 소스, URL 쿼리 문자열에 평문으로 두지 마세요. 서버 쪽 비밀 저장소와 키 제한 기능을 쓰는 게 맞습니다.

API 호출 한도, 넘으면 429가 나와요

호출 한도(quota)는 서비스 과부하와 남용을 줄이려는 제한이에요.
프로젝트, 사용자, 서비스 계정 단위로 적용될 수 있고, 넘기면 요청이 실패할 수 있습니다.

분당이나 하루 단위 rate quota는 정해진 시간이 지나야 다시 쓸 수 있어요.
Google Cloud Endpoints는 분당 할당량을 넘은 호출을 429로 거부할 수 있습니다.

예시 3 · 하루 한도를 확인하는 지훈 씨일일 한도가 10,000회인 API를 6,250회 썼다고 가정해 볼게요.
단순 계산으로 남은 호출은 10,000 - 6,250 = 3,750회예요. 리셋 시각과 한도 단위는 제공자마다 달라서 해당 문서에서 확인해야 합니다.

API 호출 오류 해결, 순서대로 하나씩 좁혀요

호출이 실패하면 요청 URL, HTTP 메서드, 필수 헤더, 인증 만료 여부, 요청 본문 형식 순서로 확인해요.
그다음 상태 코드와 응답 본문을 읽으면 원인을 나누기 쉽습니다.

주소와 메서드 확인오타가 없는지, 문서에 적힌 메서드와 같은지 봐요.

헤더와 인증 확인필수 헤더가 빠지지 않았는지, 키나 토큰이 만료되지 않았는지 봐요.

본문 형식 확인JSON처럼 문서가 정한 형식과 필드 이름이 맞는지 봐요.

응답 읽기상태 코드와 응답 본문에 적힌 오류 설명을 확인해요.

API 문서에서는 엔드포인트, 메서드, 파라미터, 인증 방식, 요청과 응답 예시, 오류 응답을 확인해야 실제로 호출할 수 있어요.
OpenAPI는 API의 구조를 기술하는 표준 사양이라 문서가 이 형식으로 제공되는 경우가 많습니다.

REST API와 JSON, API와 같은 말은 아니에요

REST API는 HTTP 리소스와 메서드의 의미를 이용해 기능을 제공하는 설계 방식 중 하나예요.
REST가 모든 웹 API의 동의어는 아닙니다.

데이터 형식으로는 JSON을 쓰는 HTTP 인터페이스가 널리 쓰여요.
Google Cloud API는 JSON HTTP와 gRPC 두 가지 인터페이스를 제공하고, TLS를 쓰는 보안 요청만 받습니다.

API가 필요 이상으로 개인정보나 토큰, 내부 식별자까지 돌려주면 과도한 데이터 노출 취약점이 될 수 있어요.
그래서 응답 필드는 서버에서 최소로 줄이는 게 좋습니다.

자주 묻는 질문

API와 REST API는 같은 말인가요?

아니요. REST API는 HTTP 리소스와 메서드의 의미를 이용하는 설계 방식 중 하나예요. 모든 웹 API가 REST인 것은 아닙니다.

API 키만 있으면 누가 호출했는지 확인되나요?

표준 API 키는 어느 프로젝트가 호출했는지 알려 줄 뿐, 호출한 사람이나 주체를 인증하지는 않아요. 사용자 권한이 필요하면 OAuth 같은 인증을 함께 씁니다.

API 키를 코드에 직접 넣어도 되나요?

권하지 않아요. 공개 저장소, 프런트엔드 소스, URL 쿼리 문자열에 평문으로 두지 말고 서버 쪽 비밀 저장소에 보관하세요.

API 호출이 계속 실패하면 무엇부터 보나요?

요청 URL, HTTP 메서드, 필수 헤더, 인증 만료 여부, 요청 본문 형식 순서로 확인하고 마지막에 상태 코드와 응답 본문을 읽어 보세요.

특정 서비스의 API 무료 호출량은 얼마인가요?

서비스마다 달라서 공통 값은 없어요. 엔드포인트, 호출 한도, 인증 방식은 해당 서비스의 공식 개발자 문서에서 확인해야 합니다.

API를 이해했다면 다음 단계로 이어서 보기

개념을 알았다면 실제로 쓰는 서비스를 하나씩 열어 보는 게 가장 빨라요.
아래 글에서 온라인 서비스 등록과 사업 서류 확인을 이어서 볼 수 있습니다.