완벽한 HTTP API: 웹 연결의 비밀을 쉽게 파헤치다

예전에 선배가 “날씨 정보는 직접 만들지 말고, 기상청 API 가져다 쓰면 돼”라고 툭 던지듯 말했던 게 아직도 기억나요. 그때는 ‘API’라는 단어가 저한테 너무 막연해서, 뭔가 고수들만 쓰는 마법 주문처럼 느껴졌거든요. 근데 지금 돌아보면 그 한마디가 제 개발자 커리어에서 꽤 중요한 첫 단추였더라고요.

우리가 스마트폰으로 친구한테 메시지 보내고, 쇼핑몰에서 상품 검색하고, 날씨 확인하는 이런 일상 뒤에는 HTTP API라는 연결고리가 거의 항상 숨어 있습니다. 오늘은 너무 딱딱한 공식 문서 느낌 말고, 친한 직장 선배가 밥 사주면서 썰 풀듯이 HTTP API를 같이 뜯어볼게요.

HTTP API 기본 이해

HTTP API가 뭐냐부터 잡고 가야 덜 헤매요. 종류는 뭐가 있는지, 그리고 “왜 다들 HTTP로 API를 만들지?” 같은 감도 같이 잡아보겠습니다. REST API 얘기도 여기서 자연스럽게 이어갈게요.

HTTP API란

HTTP API는 Application Programming Interface의 줄임말이고요, 웹 통신의 기본 언어인 HTTP(Hypertext Transfer Protocol)를 바탕으로 서로 다른 프로그램들이 데이터를 주고받을 수 있게 미리 정해둔 ‘소통 규칙’이라고 보면 됩니다. 한 문장으로 요약하면 “서로 다른 프로그램이 말 섞을 때 지켜야 하는 약속”이에요.

식당으로 비유하면 진짜 편해요. 손님(클라이언트)이 메뉴판(API)을 보고 정해진 방식, 그러니까 HTTP 메서드에 맞춰 주문을 넣으면 주방(서버)이 그 주문대로 만들어서 응답을 주는 거죠. 제가 실무에서 느낀 건, API가 잘 설계돼 있으면 “이거 어떻게 쓰지?” 고민하는 시간이 확 줄어들더라고요. 메뉴판이 친절하면 주문이 빨라지는 것처럼요.

이런 소통 방식은 IETF(국제 인터넷 표준화 기구)에서 정한 RFC 7231 문서에 정리된 HTTP 메서드를 기반으로 합니다.

클라이언트는 이런 메서드들을 써서 서버가 관리하는 자원, 예를 들면 ‘게시글’이나 ‘사용자 정보’ 같은 것들에 작업을 요청합니다.

> 월드 와이드 웹의 창시자인 팀 버너스-리(Tim Berners-Lee)는 이런 웹 서비스를 두고 ‘웹의 분산된 구조를 최대한 활용하여 시스템 간의 소통을 극대화하는 핵심 기술’이라고 말했어요.

이 말이 멋있게 들리긴 하는데, 쉽게 풀면 “특정 회사 기술에 묶이지 않고도, 웹이라는 판에서 다 같이 잘 통신하게 해주는 방식” 정도로 이해하시면 됩니다.

그리고 HTTP에서 초보 때 제일 많이 삽질하는 포인트 중 하나가 무상태(Stateless)예요. 서버가 클라이언트의 이전 요청을 기억하지 않는다는 뜻입니다. 식당으로 치면, 내가 어제도 왔고 방금도 왔고 상관없이 매번 “처음 뵙겠습니다” 모드로 응대하는 느낌이죠.

그래서 각 요청은 독립적으로 처리되고, 필요한 정보는 요청 안에 다 들어 있어야 합니다. 이게 처음엔 불편해 보이는데, 규모 커지면 진짜 큰 장점이 됩니다. 서버가 “이 사람 지난번에 뭐 했더라”를 들고 있을 필요가 없으니까, 서버를 옆으로 쭉 늘려서(수평 확장) 트래픽을 받아내기가 훨씬 쉬워져요. 로이 필딩(Roy Fielding) 박사 논문에서도 REST의 핵심 조건으로 계속 강조되는 이유가 있습니다.

HTTP API는 어떤 종류가 있을까요?

HTTP API라고 해서 한 가지 모양만 있는 건 아니고요, 설계 철학이랑 구현 방식에 따라 여러 갈래로 나뉩니다. 대표적으로 REST API, SOAP API, GraphQL API, RPC API 같은 것들이요. 다들 HTTP 위에서 돌아가긴 하는데, 데이터를 구성하고 요청/응답을 주고받는 방식이 꽤 달라요.

여기서 URI(Uniform Resource Identifier) 얘기를 빼면 또 허전하죠. 네트워크상의 자원을 고유하게 식별할 때 URI를 씁니다. 예를 들어 /users/123은 ‘users’라는 자원 묶음에서 123번 사용자를 딱 찍는 주소예요. 저도 처음엔 이 계층 구조가 낯설었는데, 며칠 만져보면 금방 익숙해지더라고요.

HTTP를 쓰면 캐싱 같은 기능도 같이 가져갈 수 있습니다. 예를 들어 반복 요청이 많은 API는 캐시를 잘 쓰면 응답 속도가 확 올라가고 서버 부담도 줄어요. HTTPS로 암호화도 기본으로 깔고 갈 수 있고요.

요즘 웹 API의 대세는 REST API입니다. 로이 필딩이 말한 것처럼 REST는 HTTP의 특성을 억지 규칙으로 덕지덕지 붙이지 않고, 있는 그대로 잘 써먹는 설계 방식이에요. 특별한 사정이 없다면 첫 API는 REST 스타일로 가는 게 제일 무난합니다. 실무에서도 “일단 REST로 맞추자”가 기본값인 팀이 많고요.

REST API

REST(Representational State Transfer)는 2000년 로이 필딩의 박사 논문에서 제안된 설계 스타일이고, 지금은 사실상 웹 API의 표준처럼 쓰입니다. 핵심은 아까 말한 것처럼 HTTP를 최대한 그대로 활용하는 거예요.

REST API는 보통 자원(Resource), 행위(Verb), 표현(Representation) 이 세 가지로 설명합니다. 예를 들어 자원은 /users/123 같은 URI로 나타내고, 조회는 GET, 삭제는 DELETE 같은 메서드로 표현하죠. 서버는 그 결과를 JSON이나 XML 같은 형태로 내려줍니다.

그리고 “RESTful”이라고 부르려면 로이 필딩이 말한 6가지 제약 조건을 충족해야 한다고들 해요.

1. 클라이언트-서버 구조 역할을 분리합니다.
2. 무상태(Stateless) 서버는 이전 요청을 기억하지 않습니다.
3. 캐시 가능(Cacheable) 응답을 재사용할 수 있습니다.
4. 계층화된 시스템 중간 서버를 둘 수 있습니다.
5. 통합 인터페이스(Uniform Interface) 일관된 방식으로 소통합니다.
6. Code-On-Demand (선택) 실행 코드를 내려 기능을 확장할 수 있습니다.

이 원칙들이 “복잡해지지 말자” 쪽으로 계속 잡아주는 역할을 합니다. REST를 처음 제대로 만났을 때 저도 “어, 생각보다 단순한데?” 싶었던 기억이 있어요. 괜히 다들 REST 얘기하는 게 아니더라고요.

HTTP API 활용 및 설계

서비스가 커질수록 “API를 어떻게 설계했냐”가 진짜 크게 돌아옵니다. 성능, 안정성, 확장성, 유지보수까지 다 연결돼요. 여기서는 실무에서 자주 부딪히는 포인트 위주로, 설계랑 사용 쪽을 같이 볼게요.

HTTP API 설계

API 설계는 기능만 던져주는 게 아니라, 다른 개발자가 “이거 이렇게 쓰면 되겠네” 하고 바로 이해할 수 있게 사용 설명서를 만드는 작업에 가깝습니다. 그래서 표준을 잘 지키는 게 생각보다 중요해요.

예를 들어 상태 코드는 이런 식으로 일관되게 쓰는 게 기본입니다. 조회 성공은 200 OK, 생성 성공은 201 Created, 잘못된 요청은 400 Bad Request, 서버 오류는 500 Internal Server ErrorCopy 이런 식으로요.

저도 처음엔 상태 코드 외우는 게 귀찮아서 대충 200/400/500만 쓰다가, 나중에 디버깅할 때 피눈물 흘린 적이 있어요. 일관된 설계 원칙을 지키면 협업할 때 오해가 줄고, 유지보수 비용도 확 내려갑니다.

그리고 이런 썰 하나 있어요. 2022년 여름에 토이 프로젝트로 동네 서점 지도 앱을 만들었는데, 그때 Naver 지도 API를 처음 써봤거든요. 문서가 꽤 친절해서 기능 구현은 금방 했는데, 더 좋았던 건 실패 케이스가 정리돼 있던 거예요. “이 에러는 왜 나는지”가 딱 보이니까 삽질 시간이 확 줄더라고요. 그때 느꼈습니다. API 자체도 중요하지만, 문서가 반쯤은 제품이구나 하고요.

실무에서는 이런 명세를 공유하려고 OpenAPI 3.0(예전 Swagger) 같은 걸 많이 씁니다. API의 설계도 역할을 해줘서, 테스트도 쉬워지고 팀원 온보딩도 빨라져요. 그리고 GET은 안전해야 한다(Safe Methods) 같은 원칙도 꼭 지켜야 합니다. 조회 요청이 서버 데이터를 바꿔버리면, 그건 나중에 진짜 큰 사고로 이어져요.

HTTP API 사용법

HTTP API를 쓰는 흐름은 단순합니다. 클라이언트가 HTTP 요청(Request)을 보내고, 서버가 HTTP 응답(Response)을 돌려주고, 클라이언트가 그걸 처리해요. 근데 실전에서는 인증, 요청 형식, 응답 파싱, 에러 처리까지 같이 따라옵니다.

인증은 보통 API 키를 헤더에 넣거나 OAuth 2.0 토큰을 쓰는 식으로 합니다. 그리고 URI, 메서드, 필요한 데이터(쿼리 파라미터나 바디)를 맞춰서 요청을 보내면 서버가 상태 코드랑 응답 본문을 내려주죠.

여기서 진짜 중요한 건 보안입니다. API는 데이터랑 기능으로 들어가는 관문이라서, 초반부터 보안을 같이 설계해야 합니다. 이거 나중에 붙이려면 생각보다 고통이에요. 저도 “일단 돌아가게 만들고 나중에 보안 붙이자” 했다가, 뒤늦게 권한 설계 뜯어고치느라 며칠 날린 적 있습니다. 그때 깨달았어요. 보안은 옵션이 아니라 기본값이더라고요.

OWASP API 보안 가이드라인에서도 기본으로 강조하는 것들이 있습니다.

1. 모든 API 통신은 HTTPS로 암호화해야 합니다. 중간에서 훔쳐보는 걸 막아야죠.
2. 민감한 기능은 OAuth 2.0 같은 검증된 인증/인가로 제어해야 합니다.

그리고 캐싱도 잘 쓰면 체감이 큽니다. 예를 들어 Cache-Control 헤더를 상황에 맞게 잡아주면, 불필요한 요청이 줄어서 응답이 빨라져요. 이런 건 초보 때는 잘 안 보이는데, 트래픽 조금만 타도 바로 체감됩니다.

HTTP API의 장단점

HTTP API도 만능은 아닙니다. 장점이 워낙 커서 기본 선택지가 되는 거지, 상황에 따라선 다른 기술이 더 맞을 때도 있어요. 장단점을 알고 쓰면 삽질을 많이 줄일 수 있습니다.

HTTP API 장점

HTTP API의 장점은 “웹 표준”이라는 데서 거의 다 나옵니다.

1. 플랫폼 독립성 HTTP는 인터넷의 공용어라서 언어, OS에 덜 묶입니다.
2. 쉬운 학습 및 사용 HTTP 자체가 단순하고 텍스트 기반이라 읽고 디버깅하기가 편합니다.
3. 기존 웹 인프라 활용 CDN, 로드 밸런서, 방화벽 같은 걸 그대로 붙이기 좋아요. 저도 새로 만든 API에 기존 로드 밸런서만 연결해서 트래픽 분산을 쉽게 했던 적이 있습니다.
4. 뛰어난 확장성 Stateless, 캐싱 같은 특성 덕분에 규모 키우기가 상대적으로 수월합니다.

이런 이유로 마이크로서비스, 클라우드 네이티브 같은 요즘 구조에서 HTTP API가 기본 뼈대가 되는 경우가 많습니다.

HTTP API 단점

장점이 많아도 단점은 분명 있어요. 아래 표는 실무에서 자주 나오는 포인트들입니다.

정리하면 이런 느낌이에요. HTTP는 텍스트 기반이라 성능이 극도로 중요한 구간에서는 손해를 볼 수 있고, 실시간 양방향 통신은 구조적으로 약합니다. 그리고 Stateless는 확장성엔 좋지만, 그만큼 클라이언트가 챙길 게 늘어나요.

마지막으로 보안은 진짜 조심해야 합니다. 외부로 열려 있는 순간부터 공격 표면이 생기거든요.

> 보안 전문가 브루스 슈나이어(Bruce Schneier)는 “이 기술의 개방성과 단순성은 양날의 검이라서, 보안 설계가 미흡하면 심각한 취약점으로 변할 수 있다”고 경고했어요.

저도 API 권한 설정을 잘못해서 데이터가 노출될 뻔한 적이 있었는데, 그때 식은땀이 쫙 나더라고요. OWASP에서 계속 “권한 설정 실패”를 상위 위험으로 꼽는 이유가 있습니다. 한 번 사고 나면 수습이 훨씬 더 힘들어요.

그래도 결론은 이겁니다. HTTP API는 웹 세상의 표준 연결 방식이고, 잘만 쓰면 안정적이고 확장 가능한 시스템을 만드는 데 정말 든든한 도구예요. 처음엔 용어가 낯설어서 겁나는데, 몇 번 호출해보고 에러도 맞아보면 금방 손에 익습니다. 삽질은 당연히 하는 거고요. 막히는 포인트 있으면 그건 정상입니다.

FAQ