엔드포인트·요청·응답·상태코드 구조
API는 서로 다른 시스템이 데이터를 주고받기 위해 사용하는 통신 방식입니다.
겉으로 보면 단순한 요청과 응답처럼 보이지만, 실제로는 정해진 규칙과 구조에 따라 동작합니다. 이 글에서는 API 호출을 이해하기 위해 반드시 알아야 할 기본 요소들을 차례대로 정리합니다.
API 호출은 하나의 약속된 절차입니다
API 호출은 “요청을 보내면 응답이 돌아온다”는 단순한 구조를 가집니다.
하지만 이 과정은 임의로 이루어지지 않고,
어디로 요청을 보낼지, 무엇을 요청할지, 어떻게 응답할지가 미리 정의되어 있습니다.
이 약속을 이해하는 것이 API 구조를 이해하는 출발점입니다.
엔드포인트는 ‘요청을 보내는 주소’입니다
엔드포인트(endpoint)는 API 요청을 보내는 정확한 주소를 의미합니다.
일반적인 웹 주소와 비슷하지만,
특정 기능이나 데이터에 접근하기 위한 경로라는 점에서 차이가 있습니다.
엔드포인트는
- 어떤 데이터를 다루는지
- 어떤 기능을 수행하는지
를 명확하게 구분하는 역할을 합니다.
API 호출에서 엔드포인트는 가장 먼저 확인해야 할 요소입니다.
요청(Request)은 무엇을 원하는지 전달합니다
요청(request)은 클라이언트가 서버에 전달하는 메시지입니다.
요청에는 다음과 같은 정보가 포함됩니다.
- 어떤 방식으로 요청하는지 (GET, POST 등)
- 어떤 데이터를 보내는지
- 추가 조건이나 인증 정보
요청은 단순한 호출이 아니라,
서버가 어떤 작업을 해야 하는지를 설명하는 지시문에 가깝습니다.
응답(Response)은 요청의 결과입니다
서버는 요청을 처리한 뒤, 그 결과를 응답(response)으로 돌려줍니다.
응답에는 보통 다음 정보가 포함됩니다.
- 처리 결과 데이터
- 처리 성공 또는 실패 여부
- 추가 안내 메시지
응답은 요청에 대한 결과 보고서와 같은 역할을 하며,
클라이언트는 이 응답을 기준으로 다음 동작을 결정합니다.
상태코드는 응답의 요약 신호입니다
상태코드(status code)는 응답 결과를 숫자로 표현한 값입니다.
응답이 성공했는지, 문제가 발생했는지를 한눈에 파악할 수 있도록 돕는 신호입니다.
상태코드는 크게 다음과 같이 구분됩니다.
- 2xx: 요청이 정상적으로 처리된 경우
- 4xx: 요청 자체에 문제가 있는 경우
- 5xx: 서버 처리 과정에서 문제가 발생한 경우
이 숫자 구분을 이해하면,
API 호출이 실패했을 때 원인을 구조적으로 파악할 수 있습니다.
상태코드는 ‘왜 실패했는지’를 알려줍니다
상태코드는 단순한 성공·실패 표시가 아닙니다.
문제가 발생했을 경우,
어디에서 문제가 생겼는지에 대한 힌트를 제공합니다.
- 요청 형식이 잘못되었는지
- 권한이 없는 요청인지
- 서버 내부 오류인지
이러한 구분은 API를 안정적으로 사용하는 데 매우 중요합니다.
API 요소들은 함께 작동합니다
엔드포인트, 요청, 응답, 상태코드는 각각 따로 존재하는 개념이 아닙니다.
이 요소들은 하나의 호출 과정 안에서 유기적으로 연결됩니다.
- 엔드포인트로 요청을 보내고
- 요청 내용을 서버가 처리하며
- 응답과 상태코드로 결과를 전달합니다
이 흐름을 이해하면,
API 호출은 더 이상 복잡한 기술이 아니라 정해진 구조를 가진 통신 절차로 보이게 됩니다.
정리
API 호출은 엔드포인트, 요청, 응답, 상태코드라는 기본 요소로 구성됩니다.
이 네 가지 요소는 서로 역할을 나누어,
시스템 간 데이터 통신을 안정적으로 유지합니다.
이 구조를 이해하면,
AI 도구나 다양한 서비스가 외부 시스템과 어떻게 연결되는지도
보다 명확하게 파악할 수 있습니다.