☀️ haejun

Today-·Total-

API

19 min read

Summary

  • API는 프로그램끼리 데이터를 주고받는 방법(=코드로 작성된 규칙)이며, 요청방식·요청자료·파라미터로 구성되고 public/private/partner로 구분된다.
  • API 요청·응답은 HTTP 프로토콜 위에서 이뤄지며, HTTP 메시지는 시작줄·헤더·빈 줄·바디로 구성된다.
  • GET은 조회용으로 파라미터를 URL에 담고, POST는 생성용으로 파라미터를 요청 바디에 담는다 — 목적·데이터 노출·멱등성이 서로 다르다.
  • 응답에는 항상 HTTP 상태 코드(2xx/4xx/5xx)가 함께 오며, Content-Type/Accept 헤더가 데이터 형식을 결정한다.
  • REST API는 URL을 리소스(명사) 중심으로 설계하고 HTTP 메서드로 동작을 표현하며, Stateless·멱등성·버전 관리·Rate Limiting 원칙을 지켜야 한다.

들어가며

“API가 뭔지는 대충 알겠는데, GET이랑 POST는 왜 나눠 쓰는 거지?”라는 의문이 API를 처음 접할 때 흔히 든다. API는 결국 프로그램끼리 데이터를 주고받는 방법일 뿐이지만, 그 방법을 실제로 구현하려면 HTTP 프로토콜의 구조, 요청 방식별 차이, REST 설계 원칙까지 알아야 한다. 이 글은 API 기본 개념 → HTTP 프로토콜 기초 → 실전 API 가이드 → REST API 설계 순서로 이어서 정리한다.

API 기본 개념

API는 한 프로그램에서 다른 프로그램으로 데이터를 주고받기 위한 방법이다. 식당의 메뉴판이 식당과 손님이 음식을 주고받는 방법이듯, API는 서버와 유저가 데이터를 주고받기 위한 방법이다. 여기서 방법은 곧 Code를 의미하며, 브라우저의 주소창이 API 요청 코드를 짜는 장소가 된다. 다만 일반 유저는 UI를 클릭하면 그 뒤에서 자동으로 API가 요청된다.

가져야 할 내용

  • 요청방식(method) : GET(조회) / POST(생성) / PUT(전체 수정) / PATCH(부분 수정) / DELETE(삭제)
  • 요청자료(endpoint) : 무슨 자료를 요청할지
  • Parameter : 자료 요청에 필요한 추가 정보

종류

  • public API : 누구나 사용 가능한 공개 API
  • private API : 사내에서 쓰는 API
  • partner API : 미리 정한 인원만 쓰는 API

예제

활용 기호 중 ?, & 두 가지만 알아도 웬만한 API를 구현할 수 있다. 네이버 검색창에 치킨이라고 검색한 URL은 다음과 같다.

https://search.naver.com/search.naver?where=nexearch&sm=top_hty&fbm=0&ie=utf8&query=%EC%B9%98%ED%82%A8

  • ?을 기준으로 앞에 있는 것(https://~~/search.naver)이 가장 기본이 되는 URL(=Root URL)이다 — 즉, 요청할 기본 주소다.
  • &는 각 파라미터의 항목을 나누어 작성할 때 사용하며 여러 개 작성할 수 있다.
  • 따라서 기본URL?조건1=값1&조건2=값2 형태로 이어진다.
  • 개발자가 아닌 이상, API를 활용하는 사용자는 query만 알면 된다.

HTTP 프로토콜 기초

API 요청·응답은 대부분 HTTP라는 프로토콜(통신 규약) 위에서 이뤄진다. HTTP 메시지의 구조를 알아야 뒤에 나오는 GET/POST 비교나 요청 바디 개념이 이해된다.

HTTP란

웹 서버 프로그램은 웹 브라우저와 통신할 때 HTTP란 프로토콜(통신 규약)을 사용한다. HTTP는 요청과 응답 양쪽 모두에 쓰이는 프로토콜이다 — 웹 브라우저가 HTTP로 요청을 보내면, 웹 서버도 HTTP로 응답한다. 이때 응답 바디의 형식(HTML, JSON, XML, CSV 등)은 Content-Type에 따라 달라진다. HTML은 그 중 한 가지 형식일 뿐, HTTP와 대등한 개념이 아니다.

HTTP 요청 메시지의 구조

HTTP 요청 메시지는 아래 4부분으로 구성된다.

HTTP 요청 메시지 예시

GET /search?query=치킨 HTTP/1.1        ← 1 Start Line (시작줄)
Host: search.naver.com                  ← ┐
User-Agent: Mozilla/5.0                 ← ├─ 2 Header (헤더)
Content-Type: application/json          ← ┘
                                         ← 3 빈 줄(헤더와 바디의 구분자)
{ "userId": "haejun" }                  ← 4 Body (바디, 선택적)
  1. Start Line(요청 라인) : 메서드 + 경로(쿼리 파라미터 포함) + HTTP 버전. GET의 ?, & 쿼리 파라미터는 이 줄에 포함된다.
  2. Header(헤더) : key: value 형태로 요청에 대한 메타정보(데이터 자체가 아니라 처리 방법)를 담는다.
    • Host : 요청 대상 서버 도메인
    • Content-Type : 바디 형식 지정(바디가 있을 때 필수)
    • Authorization : 인증 토큰/API Key
    • Accept : 클라이언트가 원하는 응답 형식
    • Cookie : 세션/인증 정보
  3. 빈 줄 : 헤더가 끝나고 바디가 시작됨을 알리는 구분자다.
  4. Body(바디) : 실제 전송 데이터다. GET은 관례상 비어있고, POST/PUT/PATCH에서 주로 사용한다.

헤더 vs 바디

헤더는 이 요청을 어떻게 처리해야 하는지에 대한 부가 설명서이고, 바디는 실제로 주고받는 화물(데이터)이다. GET의 파라미터는 1(URL)에, POST의 데이터는 4(Body)에 들어간다.

HTML

HTML은 문서의 한 종류이자 웹 페이지를 위한 표준 언어다. 마크업 언어라고 부르며, <div>와 같은 표시를 태그(tag)라고 부른다. HTML은 구조가 비교적 복잡하여 API에서는 HTML 대신 CSV, JSON, XML을 선호하며, 보통 웹 기반 API는 JSON, XML을 많이 사용한다.

API 가이드

실제 API 요청은 GET(조회)과 POST(생성)를 가장 많이 쓰며, 둘은 파라미터 위치·노출·멱등성이 다르다. 요청엔 바디가, 응답엔 상태 코드가 따라오고, Auth·HTTPS·CORS는 실무에서 꼭 확인해야 할 요소다.

카카오 책 검색 API를 예로 들면, 요청(request)은 프론트엔드에서 백엔드로 아래 규칙에 맞게 보낸다.

  • 주소(https://dapi.kakao.com/v3/search/book) : 기본이 되는 URL
  • 전송방식 : GET
    • GET : 검색어를 주소창(URL)에 넣어 보내는 방식이다. URL 길이는 브라우저·서버 구현체마다 실무상 한계가 있으나(예: 구형 IE 약 2,083자), HTTP 표준이 정한 고정 스펙은 아니다. 길이 제약이나 민감정보 전송이 문제될 경우 POST 방식을 사용한다.
    • POST : 주소창이 아닌 요청 바디(body)에 담아 전송하는 방식이다.
  • 보낼 것 : query(검색어, 필수) / sort(정렬 방식, 선택) / target(검색 대상, 선택)

응답(response)은 백엔드에서 프론트엔드로 JSON(일반적인 추세) 또는 XML 형식으로 온다. title은 도서 제목, contents는 도서 소개, thumbnail은 도서 표지 섬네일 URL을 뜻한다. 응답 본문 외에 HTTP 상태 코드가 함께 오며, 요청 처리 성공/실패를 나타낸다.

핵심 확인 사항은 Auth, HTTPS, CORS다.

  • Auth : 요청자를 식별/인가하는 절차다. API Key 방식 외에도 OAuth, Bearer Token(JWT), Basic Auth 등 다양한 방식이 있다.
  • HTTPS : 보안 연결 제공 여부다.
  • CORS : 브라우저가 다른 출처(origin)로의 요청을 허용할지 서버 응답 헤더(Access-Control-Allow-Origin 등)로 판단하는 보안 메커니즘이다. 서버가 허용하지 않으면 브라우저가 응답을 차단한다.

GET vs POST 비교

구분GETPOST
목적리소스 조회리소스 생성(또는 서버 상태 변경)
데이터 위치URL 쿼리 파라미터(?key=value)요청 바디(body)
데이터 노출URL에 그대로 노출 → 브라우저 히스토리, 서버 로그에 남음바디에 담겨 URL에는 노출되지 않음(암호화는 아니므로 HTTPS는 별개로 필요)
길이 제한브라우저·서버 구현체별 실무 한계 있음바디 크기 한도(서버 설정)까지 가능, 상대적으로 자유로움
캐시브라우저/CDN이 기본적으로 캐시 가능기본적으로 캐시되지 않음
북마크·공유URL만으로 요청 상태 재현 가능(북마크 가능)불가능(바디는 URL에 없음)
멱등성멱등(몇 번 호출해도 서버 상태 동일)비멱등(호출할 때마다 새 리소스 생성될 수 있음)
브라우저 뒤로가기안전하게 재요청됨재요청 시 “양식 재제출” 경고가 뜨는 경우가 많음

데이터 노출과 보안

GET은 파라미터가 URL에 그대로 남기 때문에 비밀번호·인증토큰 같은 민감정보 전송에 부적합하다. POST가 URL에 노출은 안 되지만, 그 자체로 암호화되는 것은 아니므로 민감정보는 반드시 HTTPS와 함께 사용해야 한다.

사용 예시

  • GET 예시 — 검색/조회 : 네이버에서 치킨을 검색하면 브라우저가 검색어를 URL에 실어 요청한다(GET https://search.naver.com/search.naver?query=치킨). 조회만 하고 서버 데이터를 바꾸지 않으므로 GET이 적합하며, URL만 있으면 그대로 재요청·북마크·공유할 수 있다.

  • POST 예시 — 로그인/회원가입 : 로그인 폼에 아이디·비밀번호를 입력하고 제출하면, 이 값들은 URL이 아닌 요청 바디에 담겨 전송된다.

    로그인 요청 바디 예시

    { "userId": "haejun", "password": "****" }

    비밀번호가 URL에 남으면 브라우저 히스토리·서버 로그에 그대로 노출되므로 반드시 바디로 보내야 한다.

  • POST 예시 — 게시글 작성 : 게시판에 새 글을 작성해 저장하는 것도 서버에 새 리소스(글)를 생성하는 동작이므로 POST를 사용한다(POST /posts + 바디에 { "title": "...", "content": "..." }).

요청 바디(Request Body)

앞서 본 HTTP 메시지 구조의 4(Body)에 해당하며, 요청과 함께 전송할 실제 데이터를 담는 부분이다.

  • URL 쿼리 파라미터와의 차이
    • 쿼리 파라미터 : URL에 노출되며, 문자열 길이·형식 제약이 있다(단순 key=value 위주).
    • 바디 : URL과 분리되어 있어 구조화된 데이터(JSON, XML, 폼 데이터 등)를 자유롭게 담을 수 있다.
  • 바디의 형식은 Content-Type 헤더로 지정한다.
    • application/json : JSON 형식(API에서 가장 흔히 사용)
    • application/x-www-form-urlencoded : key=value&key2=value2 형태의 폼 데이터
    • multipart/form-data : 파일 업로드처럼 여러 파트로 구성된 데이터
  • GET은 관례상 바디를 사용하지 않고 쿼리 파라미터만 사용하며, 바디가 필요한 요청(생성/수정)은 POST·PUT·PATCH로 처리한다.

HTTP 상태 코드

  • 2xx : 성공 (예: 200 OK, 201 Created)
  • 4xx : 클라이언트 오류 (예: 400 Bad Request, 401 Unauthorized, 404 Not Found)
  • 5xx : 서버 오류 (예: 500 Internal Server Error)

Content-Type / Accept 헤더

  • Content-Type : 요청/응답 바디가 어떤 형식(JSON, XML 등)인지 명시하는 헤더
  • Accept : 클라이언트가 어떤 형식으로 응답받고 싶은지 서버에 요청하는 헤더

REST API 설계

API는 기본적으로 CRUD(Create / Read / Update / Delete)를 활용한다. REST(REpresentational State Transfer)는 아래 원칙을 지향하는 아키텍처 스타일이다.

  • Stateless : 서버가 클라이언트의 이전 요청 상태를 저장하지 않는다(각 요청은 그 자체로 완전해야 한다). 매번 처음 온 손님처럼 응대하는 것과 같아서, 필요한 정보(로그인 토큰 등)는 매 요청마다 다시 실어 보내야 한다.
  • 리소스 중심 설계 : URL은 ‘동작’이 아닌 ‘리소스(자원)‘를 나타낸다.
  • Uniform Interface : HTTP 메서드로 리소스에 대한 동작을 일관되게 표현한다. 어떤 리소스든 “조회는 GET, 생성은 POST”라는 같은 규칙이 통하므로, 처음 보는 API도 이 규칙만 알면 바로 읽을 수 있다.

기본 설계 방법

URL에서는 동사를 사용하지 않는다. 오직 명사만 존재해야 하며, /createMovie처럼 설계하는 것은 잘못된 예다. 영화 인셉션을 예로 들면 컬렉션(Collection)은 Movies, DB 고유 식별자(unique identifier)는 Inception이 되어 /movies/inception으로 표현한다.

HTTP methods를 활용해 인터랙션해야 한다.

  • GET : 읽기 / POST : 생성 / PUT : 전체 수정 / PATCH : 부분 수정 / DELETE : 삭제
    • GET /movies : 영화 목록 모두 불러오기
    • POST /movies : 영화 생성
  • 단, PUT, PATCH, DELETE는 컬렉션이 아닌 고유 식별자를 활용하여 사용한다.
    • DELETE /movies/inception : 영화 목록 중 인셉션 삭제

멱등성(Idempotency)은 같은 요청을 여러 번 보내도 결과가 같은지 여부를 뜻한다. GET, PUT, DELETE는 멱등(몇 번을 호출해도 서버 상태가 동일)하지만, POST는 멱등하지 않다(호출할 때마다 새 리소스가 생성된다). 재시도 로직을 설계할 때는 멱등한 메서드만 안전하게 재요청할 수 있다.

버전 관리는 API 스펙이 바뀔 때 기존 클라이언트가 깨지지 않도록 버전을 명시하는 것이다(예: /v1/movies, /v2/movies).

쿼리 파라미터(query parameter) 활용

매번 검색 시 해당 URL을 새롭게 만드는 것이 아니라, API에 pagination(페이지 번호)을 추가해 활용하는 방식이다(예: /movies?page=5).

Rate Limiting

서버 과부하 방지를 위해 클라이언트별 요청 횟수를 제한하는 정책이다(예: 분당 60회). 놀이기구를 한 사람이 계속 줄만 서서 타면 다른 사람이 못 타듯, 한 클라이언트가 요청을 독점하지 못하게 막는 장치다. 제한 초과 시 보통 429 Too Many Requests 상태 코드로 응답한다.

마치며

API를 이해하는 핵심은 다음과 같다.

  • API는 프로그램끼리 데이터를 주고받는 방법이며, 그 통신은 HTTP 프로토콜(시작줄·헤더·바디 구조) 위에서 이뤄진다.
  • GET은 조회용으로 파라미터를 URL에, POST는 생성용으로 데이터를 바디에 담아 보내며, 목적·노출·멱등성이 서로 다르다.
  • REST API는 URL을 리소스 중심으로 설계하고 HTTP 메서드로 동작을 표현하며, Stateless·멱등성·버전 관리·Rate Limiting 원칙을 지켜야 예측 가능하고 안전해진다.

Reference

Graph View