웹 APIWeb API
프로그램이 HTTP 와 그 위의 연결로 다른 시스템의 기능 · 데이터를 쓰게 하는 기계용 인터페이스를 묶은 것으로, 요청 · 응답 방식(REST · GraphQL · gRPC) · 서버가 먼저 보내는 방식(웹소켓 · SSE · 웹훅) · 그 계약을 적는 명세(OpenAPI)를 다룬다.
1요약
- 웹 API 는 프로그램끼리 HTTP 의미 규칙(RFC 9110 · 2022) 위에서 기능을 주고받는 인터페이스를 묶은 것으로, 요청 · 응답 셋(REST · GraphQL · gRPC)과 서버가 먼저 보내는 셋(웹소켓 · SSE · 웹훅) 이 이 위에서 돌고 그 계약은 OpenAPI 3.2.1(2026-09) 같은 명세로 적는다.
- 방식을 잘못 고르면 화면 하나에 요청이 늘거나 소식을 놓친다 — 가정 값으로 주문 상세 화면은 REST 로 요청 3번, GraphQL 로 1번이고, 결제 완료를 폴링으로 기다리면 묻는 간격만큼 늦는다.
- 「느리다 · 놓친다 · 두 번 처리된다」는 누가 먼저 말하고 연결이 얼마나 사는가로 가른다 — 요청마다 끝나는 연결이면 요청 수와 재시도를, 열어 둔 연결이면 재연결 기록을, 역할을 바꾼 웹훅이면 중복 수신을 본다.
2등장 배경
2000년 Fielding 의 박사 논문 5장이 자원 주소와 정해진 메서드로 다루는 REST 를 정리했고, 웹 API 는 그 뒤 HTTP 위의 JSON 응답으로 퍼졌다. 그런데 브라우저가 서버 소식을 받으려면 계속 다시 묻는 폴링밖에 없어, 2011년 RFC 6455 가 HTTP 연결을 양방향으로 바꾸는 웹소켓을 정했고 WHATWG HTML 은 한 방향 스트림인 SSE(9.2절)를 둔다.
화면마다 REST 요청이 늘어나자 2015년 7월 GraphQL 첫 공개 명세가 «응답 모양을 질의로 고르는» 방식을 냈고, 같은 해 3월 Google 이 사내 RPC 의 다음 판을 gRPC 로 공개했다(gRPC About). 회사 밖 시스템이 사건을 알려 주는 웹훅은 W3C WebSub 가 콜백 주소 확인 · 서명 · 재전송 규칙을 표준으로 묶었다.
지금은 한 서비스가 여러 방식을 함께 쓴다. 공개 API 는 REST + OpenAPI, 화면 조립은 GraphQL, 내부 서비스 사이는 gRPC, 외부 사건은 웹훅, 화면 갱신은 SSE · 웹소켓이 맡는 식이다.
3쉽게 이해하기 — 도매 본사와 거래하는 동네 가게
동네 가게 주인은 도매 본사와 거래한다. 평소에는 품목별 창구에서 정해진 서식으로 묻고, 여러 창구를 돌기 번거로우면 주문서 한 장에 필요한 칸만 적어 낸다. 본사는 창고와 직통 내선으로 재고를 잡고, 은행은 결제가 끝나면 본사가 알려 둔 우편함에 소식을 넣는다. 배송 소식은 본사가 매장 안내 방송으로 먼저 알려 주고, 급한 상담은 무전기로 서로 바로 말한다.
그림 1 · 가게와 본사는 창구 · 주문서로 묻고 답하며, 본사가 먼저 알릴 때는 방송 · 무전기를 쓰고, 은행은 알려 둔 우편함으로 찾아온다.
그림 2 · 창구를 여러 번 도는 쪽은 창구가 서식을 정해 미리 쌓아 둘 수 있고, 주문서 한 장은 가게가 칸을 정해 한 번에 끝나지만 미리 쌓아 둘 수 없다.
| 비유 속 역할 | 실제 이름 | 실제로 하는 일 |
|---|---|---|
| 가게 주인 | 클라이언트(앱 · 브라우저) | 요청을 시작하고 받은 응답으로 화면을 만든다 |
| 품목별 창구 | REST | 자원마다 주소를 두고 GET · POST · PUT · DELETE 로 다룬다 |
| 주문서 한 장 | GraphQL | 필요한 필드만 적은 질의 하나로 여러 자원을 받는다 |
| 직통 내선 | gRPC | 미리 정한 서비스 · 메서드를 HTTP/2 위에서 바로 부른다 |
| 우편함 주소 | 웹훅 | 제공자가 사건마다 받는 쪽 주소로 새 요청을 보낸다 |
| 안내 방송 | SSE | 열어 둔 응답으로 서버가 이벤트를 차례로 보낸다 |
| 무전기 | 웹소켓 | 한 연결에서 양쪽이 아무 때나 메시지를 보낸다 |
| 거래 안내 책자 | API 설계 · OpenAPI 명세 | 어떤 주소 · 필드 · 오류가 있는지 기계가 읽게 적는다 |
⚠ 비유가 맞지 않는 곳: 안내 방송은 매장 안 모두가 듣지만, SSE 는 연결을 연 클라이언트 하나에게만 보낸다. 또 은행이 우편함을 찾아오는 일은 실제로는 제공자가 클라이언트가 되어 HTTPS 요청을 보내는 것이라, 받는 쪽이 밖에서 닿는 공개 주소를 가져야 한다.
4구조 — 계약 · 방식 · 형식 · 전송
아래 여섯 토픽은 방식 다섯과 계약 하나로 나뉜다. 방식은 «클라이언트가 먼저 묻는가, 서버도 먼저 보내는가»로 두 무리가 되고, 본문 형식은 데이터 교환 형식이, 연결 자체는 웹 시스템 구조 · 네트워크가 맡는다.
그림 3 · 계약(명세)이 맨 위에서 방식 여섯을 묶고, 방식은 클라이언트가 먼저 묻는 셋과 서버도 먼저 보내는 셋으로 나뉘며, 아래 형식 · 전송은 데이터 교환 형식과 웹 시스템 구조 · 네트워크가 맡는다.
| 토픽 | 푸는 문제 | 주고받는 단위 | 계약 문서 | 대표 표준 |
|---|---|---|---|---|
| REST | 자원을 주소 하나 · 메서드 몇 개로 다룬다 | 자원 표현(JSON 등) | OpenAPI paths | Fielding 2000 5장 · RFC 9110 |
| GraphQL | 화면마다 다른 필드 조합을 한 번에 받는다 | 질의 · data · errors | 스키마 | GraphQL 2025 |
| gRPC | 서비스 사이 잦은 호출을 정해진 메서드로 | 길이 접두 메시지 | .proto | gRPC over HTTP2 |
| 웹소켓 · SSE | 서버 소식을 다시 묻지 않고 받는다 | 메시지 · 이벤트 | 없음(구현이 정함) | RFC 6455 · WHATWG HTML 9.2 |
| 웹훅 | 남의 시스템 사건을 바로 알게 한다 | 사건 하나 = POST 하나 | OpenAPI webhooks | W3C WebSub |
| API 설계 · OpenAPI 명세 | 주소 · 필드 · 오류를 기계가 읽게 적는다 | 명세 문서 | — | OpenAPI 3.2.1 · RFC 9457 |
🔑 방식 다섯은 HTTP 를 함께 쓰지만, 무엇을 정하느냐가 다르다 — REST 는 주소를, GraphQL 은 응답 모양을, gRPC 는 메서드를, 웹소켓 · SSE · 웹훅은 «누가 먼저 말하나»를 정한다.
5동작 — 주문 하나의 생애
쇼핑 앱이 주문 하나를 만들고 결제 완료를 화면에 띄우는 사례다. 도메인 shop.example 은 문서용 예약 이름(RFC 2606)이고, 주문 o-5521 · 이벤트 id 42 는 설명용 가정 값이다.
- 앱 개발자가 OpenAPI 문서의
paths에서/v1/orders·post의 요청 필드와 오류 형식을 확인한다(OpenAPI 3.2.1 4.1.1). - 앱이
POST https:를 보내고/ / shop. example/ v1/ orders 201 Created·Location: /를 받는다(RFC 9110 9.3.3 · 15.3.2).v1/ orders/ o-5521 - 주문 서버가 재고 서비스에 gRPC 로
POST /·inventory. v1. Stock/ Reserve content-type: application/를 보내고, 트레일러로grpc grpc-status: 0을 받는다(gRPC over HTTP2). - 앱 화면이 주문 · 상품 · 배송을
POST /graphql질의 하나로 묻고, 질의와 같은 모양의data를 받는다(GraphQL 2025 2.4 · 7.1.1). - 앱이
GET /·v1/ orders/ o-5521/ events Accept: text/으로 SSE 스트림을 열어 둔다(WHATWG HTML 9.2).event-stream - 결제 대행사가 웹훅으로
POST https:에/ / shop. example/ hooks/ payment X-Hub-Signature: sha256=을 붙여 보내고, 주문 서버는 서명을 확인한 뒤 처리를 미루고… 204로 바로 답한다(W3C WebSub 7 · 7.1). - 주문 서버가 열어 둔 스트림에
event: status·id: 42·data: {"status":를 보내 화면을 바꾼다."PAID"} - 연결이 끊겼다 다시 붙으면 브라우저가
Last-Event-ID: 42를 보내, 서버는 그 뒤 이벤트부터 보낸다(WHATWG HTML 9.2).
그림 4 · 주문 하나에 방식 다섯이 차례로 쓰이고, 결제 소식은 제공자가 먼저 보낸 웹훅(6단계)이 열어 둔 SSE 스트림(7단계)으로 이어져 앱이 다시 묻지 않는다.
그림 5 · 서버가 먼저 말하는 길은 둘뿐이다 — 연결을 열어 두거나(오른쪽 아래), 제공자가 클라이언트로 역할을 바꿔 새 요청을 보낸다(왼쪽 아래).
🔑 웹훅은 새 통신 방식이 아니라 역할을 바꾼 HTTP 요청이다 — 그래서 SSE · 웹소켓은 «연결을 오래 살리는 일»이, 웹훅은 «공개 주소 · 서명 · 중복 수신»이 설계의 중심이 된다.
6비교 — 방식 다섯의 선택 축
| 방식 | 먼저 보내는 쪽 | 연결 수명 | 응답 모양을 정하는 쪽 | 받는 쪽이 놓치면 | 맞는 쓰임 |
|---|---|---|---|---|---|
| REST | 클라이언트 | 요청마다 | 서버(주소마다 고정) | 다시 요청 · 안전 · 멱등 메서드만 자동 재시도(RFC 9110 9.2.2) | 공개 API · 캐시가 필요한 조회 |
| GraphQL | 클라이언트(구독은 예외) | 요청마다 | 클라이언트(질의) | 일부 필드만 null + errors(GraphQL 2025 6.4.4) | 화면마다 다른 조합 |
| gRPC | 클라이언트 | 요청마다 또는 스트림 | 서버(.proto 고정) | 14 UNAVAILABLE 만 백오프 재시도 권장(gRPC Status Codes) | 서비스 사이 잦은 호출 |
| 웹소켓 | 양쪽 | 열어 둠 | 구현이 정함 | 재연결 · 복구 규칙을 응용이 만듦(RFC 6455) | 채팅 · 협업 편집 |
| SSE | 서버(한 방향) | 열어 둠 | 서버 | Last-Event-ID 로 이어 받음(WHATWG HTML 9.2) | 상태 알림 · 진행률 |
| 웹훅 | 제공자 | 사건마다 새 요청 | 제공자 | 2xx 가 없으면 제공자가 한도 안에서 재전송(W3C WebSub 7) | 회사 밖 시스템의 사건 |
분석서버 소식이 필요 없으면 REST(조회 캐시) · GraphQL(화면 조립) · gRPC(내부 호출) 가운데 고르고, 소식을 받는 쪽이 브라우저면 SSE(한 방향) · 웹소켓(양방향), 받는 쪽이 공개 주소를 가진 서버면 웹훅을 쓴다. 근거는 표의 「먼저 보내는 쪽」 · 「받는 쪽이 놓치면」 열 — 복구 규칙이 표준에 있는 SSE · 웹훅과 달리 웹소켓은 응용이 직접 만든다.
7실무 진단 — 방식별 실패 위치 가르기
분석먼저 «HTTP 상태 코드가 성공인데도 실패했는가»를 본다. gRPC 는 트레일러, GraphQL 은 본문 errors 에 실패를 담아 HTTP 200 이 와도 실패일 수 있고, 웹훅 · SSE 는 «받았는가»와 «처리했는가»가 따로다(gRPC over HTTP2 · GraphQL 2025 7.1.1 · W3C WebSub 7).
| # | 증상 | 의심 원인 | 방식 | 확인 명령 · 자료 | 판정 기준(근거) |
|---|---|---|---|---|---|
| 1 | 같은 결제가 두 번 처리됨 | 늦은 응답으로 제공자가 재전송 | 웹훅 | 수신 로그의 사건 id · 응답 시간 | 2xx 는 받음만 뜻함 — 처리 전에 바로 답하고 사건 id 로 중복을 거름(W3C WebSub 7) |
| 2 | 재연결 뒤 상태 변경이 빠짐 | 이벤트에 id 가 없음 | SSE | curl -N -H "Accept: text/event-stream" https: | 출력에 id: 줄이 없으면 Last-Event-ID 가 가지 않음(WHATWG HTML 9.2) |
| 3 | HTTP 200 인데 호출이 실패로 끝남 | 오류가 트레일러에 실림 | gRPC | 응답 트레일러의 grpc-status · grpc-message | 0 이 아니면 실패 · 상태는 성공일 때도 트레일러로 옴(gRPC over HTTP2) |
| 4 | 화면 일부가 비고 나머지는 정상 | 필드 실행 오류 | GraphQL | 응답 본문의 errors 배열 · path | data 와 errors 가 함께 오면 그 위치만 null(GraphQL 2025 6.4.4 · 7.1) |
HTTP 상태 코드가 실패면 방식과 무관하게 웹 시스템 구조 쪽(프록시 · WAS)부터 본다. 상태가 성공인데 결과가 틀리면 표의 방식 열로 들어가, 서버가 먼저 보내는 방식(1 · 2행)은 수신 기록을, 요청 · 응답 방식(3 · 4행)은 본문 · 트레일러를 본다.
8시험 대비
시험에서는 REST · GraphQL · gRPC 각각의 개념과 특징을 묻는 정의 · 특징형, 그리고 실시간 알림 · 외부 연동이 있는 서비스에서 방식을 고르는 비교형 · 구현 · 설계형이 나올 수 있다. 정의형은 방식 하나를 «무엇을 정하는가(주소 · 응답 모양 · 메서드)» 축으로 쓰고, 비교형은 먼저 보내는 쪽 × 연결 수명 도표를 놓고 선택 기준을 적는다.
- 개요 — 웹 API 정의 · HTTP 의미 규칙(RFC 9110) · REST(2000) → 웹소켓(2011) → GraphQL · gRPC(2015)
- 구성 — 그림 3 지도(계약 · 요청 · 응답 셋 · 이벤트 · 푸시 셋) + 토픽별 계약 문서 표
- 처리 흐름 — 그림 4 순서도(REST 생성 → gRPC 재고 → GraphQL 조회 → 웹훅 → SSE)
- 핵심 원리 — 그림 5 먼저 보내는 쪽 × 연결 수명 사분면 · 웹훅 = 역할을 바꾼 요청
- 비교 · 선택 — 방식 다섯 표(응답 모양을 정하는 쪽 · 놓쳤을 때 복구)
- 운영 고려 — HTTP 200 인데 실패(트레일러 · errors) · 웹훅 서명(RFC 9421 · WebSub 7.1) · 오류 본문(RFC 9457)
꼭 쓸 키워드
RESTGraphQLgRPCOpenAPI웹소켓SSE웹훅멱등Last-Event-IDgrpc-status
다른 답안과 차이를 내려면 방식을 나열하지 않고, 「먼저 보내는 쪽 × 연결 수명」 사분면 도표에 방식을 놓아 웹훅이 왜 공개 주소 · 서명을 요구하는지 보인다.
9오해와 사실
- 오해GraphQL 은 REST 를 대체하는 더 새로운 REST 다.사실GraphQL 은 응답 모양을 클라이언트 질의가 정하는 다른 방식이고, POST 로 질의를 보내면 주소마다 응답이 같다는 전제가 없어 REST 처럼 HTTP 캐시에 기대기 어렵다(RFC 9110 9.2.3 · GraphQL over HTTP draft 4).
- 오해HTTP 200 을 받으면 API 호출은 성공이다.사실gRPC 는 상태를 트레일러의 grpc-status 로, GraphQL 은 실패 필드를 errors 로 따로 알리므로 본문 · 트레일러까지 봐야 한다(gRPC over HTTP2 · GraphQL 2025 7.1).
- 오해웹훅에 2xx 로 답하면 처리가 끝났다는 뜻이다.사실WebSub 는 2xx 를 «받았다»는 뜻으로 두고 처리 완료를 요구하지 않으며, 실패하면 제공자가 다시 보내므로 받는 쪽은 사건 id 로 중복을 거른다(W3C WebSub 7).
10핵심 정리
| 방식 | 정하는 것 | 먼저 보내는 쪽 | 연결 | 계약 · 형식 | 실패를 보는 곳 |
|---|---|---|---|---|---|
| REST | 자원 주소 · 메서드 | 클라이언트 | 요청마다 | OpenAPI paths · JSON | HTTP 상태 코드 · RFC 9457 본문 |
| GraphQL | 응답 모양 | 클라이언트 | 요청마다 | 스키마 · data · errors | 본문 errors · path |
| gRPC | 서비스 · 메서드 | 클라이언트 | 요청 · 스트림 | .proto · Protobuf | 트레일러 grpc-status |
| 웹소켓 | 양방향 메시지 | 양쪽 | 열어 둠 | 구현이 정함 | 연결 종료 · 재연결 기록 |
| SSE | 이벤트 순서 | 서버 | 열어 둠 | text/event-stream | id · Last-Event-ID |
| 웹훅 | 사건 알림 | 제공자 | 사건마다 | OpenAPI webhooks · 서명 | 수신 로그 · 재전송 기록 |
| OpenAPI 명세 | 계약 문서 | — | — | OpenAPI 3.2.1 | 명세 ↔ 실제 응답 대조 |
11참고 문헌
- 먼저 볼 문헌
- ★ RFC 9110 HTTP Semantics — 안전 · 멱등 메서드(9.2.1 · 9.2.2)와 캐시 가능한 메서드(9.2.3)를 원문으로 볼 때
- ★ OpenAPI Specification v3.2.1 — paths 와 webhooks 필드(4.1.1)로 API 계약을 적는 법을 볼 때
- ★ GraphQL Specification (September 2025 Edition) — 연산 종류(2.4)와 data · errors 가 함께 오는 응답(6.4.4 · 7.1)을 볼 때
- ★ gRPC over HTTP2 (PROTOCOL-HTTP2.md) — 경로 /서비스/메서드 · application/grpc · 트레일러의 grpc-status 를 볼 때
- ★ WebSub (W3C Recommendation) — 콜백 주소 확인(5.3) · 서명(7.1) · 2xx 의 뜻과 재전송(7)을 볼 때
- 본문 근거
- HTML Living Standard 9.2 Server-sent events — WHATWG · 2026-11 ·
html.spec.whatwg.org/multipage/server-sent-events.html· 확인 2026-11-14 - RFC 6455 The WebSocket Protocol — IETF · 2011-12 ·
www.rfc-editor.org/rfc/rfc6455· 확인 2026-11-14 - GraphQL over HTTP (Current Working Draft) — GraphQL Foundation · 2026-11 ·
http-spec.graphql.org/draft/· 확인 2026-11-14 - GraphQL Specification (July 2015 Edition) — Facebook · 2015-07 ·
spec.graphql.org/July2015/· 확인 2026-11-14 - gRPC Core concepts, architecture and lifecycle — gRPC Authors · 2026-11 ·
grpc.io/docs/what-is-grpc/core-concepts/· 확인 2026-11-14 - gRPC Status Codes — gRPC Authors · 2026-11 ·
grpc.io/docs/guides/status-codes/· 확인 2026-11-14 - About gRPC — gRPC Authors · 2026-11 ·
grpc.io/about/· 확인 2026-11-14 - Architectural Styles and the Design of Network-based Software Architectures, Chapter 5 Representational State Transfer (Roy T. Fielding · UC Irvine 박사 논문) — University of California Irvine · 2000-06 ·
ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm· 확인 2026-11-14 - RFC 9457 Problem Details for HTTP APIs — IETF · 2023-07 ·
www.rfc-editor.org/rfc/rfc9457· 확인 2026-11-14 - RFC 9421 HTTP Message Signatures — IETF · 2024-02 ·
www.rfc-editor.org/rfc/rfc9421· 확인 2026-11-14 - RFC 2606 Reserved Top Level DNS Names — IETF · 1999-06 ·
www.rfc-editor.org/rfc/rfc2606· 확인 2026-11-14 - curl man page — curl project · 2026-11 ·
curl.se/docs/manpage.html· 확인 2026-11-14