시스매

개발자를 위한 HTTP와 REST API 핸드북 원리부터 실전 활용까지

15 min read

2025-08-11 22:20

Tags:

개발자를 위한 HTTP와 REST API 핸드북 원리부터 실전 활용까지

1. 만들어진 이유, HTTP와 REST의 탄생 배경

1-1. HTTP, 웹의 근간을 이루는 약속

HTTP(Hypertext Transfer Protocol)는 1990년대 초 팀 버너스리가 제안한 월드 와이드 웹(WWW)의 핵심 프로토콜입니다. 인터넷 초기에는 단순히 문서를 주고받는 것이 주된 목적이었으며, 이를 위해 클라이언트(웹 브라우저)와 서버(웹 서버)가 통신하는 규약이 필요했습니다. HTTP는 이 역할을 담당하며, 우리가 웹사이트를 탐색하고 데이터를 주고받을 수 있게 하는 가장 기본적인 약속입니다.

1-2. REST, HTTP를 활용하는 우아한 설계 방식

REST(Representational State Transfer)는 HTTP가 세상에 나온 지 약 10년 후, 2000년 로이 필딩(Roy Fielding)의 박사 학위 논문에서 처음 소개된 **‘분산 하이퍼미디어 시스템을 위한 아키텍처 스타일’**입니다. 당시 웹 서비스들은 복잡하고 비효율적인 프로토콜을 사용하고 있었는데, 필딩은 “왜 HTTP가 가진 강력한 기능을 제대로 활용하지 못하는가?”라는 의문을 제기합니다. REST는 HTTP 프로토콜의 장점을 최대한 활용하여, 웹의 확장성을 해치지 않고 효율적으로 통신하기 위한 설계 원칙의 집합인 것입니다. 쉽게 말해, HTTP라는 언어를 더 아름답고 효율적으로 사용하는 문법이라고 할 수 있습니다.

2. HTTP의 구조와 작동 방식

2-1. HTTP 요청과 응답의 순환

HTTP는 기본적으로 요청(Request)과 응답(Response)이라는 단순한 구조로 동작합니다.

  1. **클라이언트 (예: 웹 브라우저)**가 서버에게 특정 정보를 달라고 요청합니다.

  2. 서버는 그 요청을 처리하고 결과를 클라이언트에게 응답합니다.

이 과정은 마치 도서관에서 책을 빌리는 것과 같습니다. 사용자가 사서에게 “특정 책을 주세요”라고 요청하고, 사서는 그 책을 찾아 건네주는 응답을 하는 구조입니다.

2-2. HTTP 요청 메시지의 구성 요소

  • 시작 줄(Start Line)

    • HTTP 메서드 (Method): 서버가 수행해야 할 동작을 정의합니다. (GET, POST, PUT, DELETE 등)

    • 요청 대상 (Request Target): 요청하려는 리소스의 경로를 나타냅니다. (예: /users/1)

    • HTTP 버전 (Version): 클라이언트가 사용하는 HTTP 버전입니다. (HTTP/1.1, HTTP/2.0 등)

  • 헤더 (Headers)

    • 요청에 대한 추가 정보를 담습니다. (예: Content-Type, Authorization, Host 등)

  • 본문 (Body)

    • POST, PUT 메서드처럼 클라이언트가 서버로 전송할 데이터(예: 회원가입 정보)가 포함됩니다. GET 요청에는 보통 본문이 없습니다.

2-3. HTTP 응답 메시지의 구성 요소

  • 시작 줄(Status Line)

    • HTTP 버전 (Version): 서버가 사용하는 HTTP 버전입니다.

    • 상태 코드 (Status Code): 요청의 처리 결과를 나타내는 3자리 숫자입니다. (예: 200 OK, 404 Not Found, 500 Internal Server Error)

    • 상태 메시지 (Status Text): 상태 코드를 사람이 이해하기 쉽게 설명합니다.

  • 헤더 (Headers)

    • 응답에 대한 추가 정보를 담습니다. (예: Content-Type, Server, Date 등)

  • 본문 (Body)

    • 서버가 클라이언트에게 전달하는 실제 데이터(HTML 문서, JSON 데이터 등)가 담겨 있습니다.

2-4. HTTP의 비상태성(Stateless)

HTTP의 중요한 특징 중 하나는 **“비상태성(Stateless)“**입니다. 이는 서버가 클라이언트의 이전 요청에 대한 정보를 기억하지 않는다는 의미입니다. 모든 요청은 독립적으로 처리되며, 서버는 매 요청마다 새로운 요청으로 간주합니다. 이로 인해 서버는 수많은 클라이언트의 요청을 효율적으로 처리할 수 있지만, 클라이언트의 상태를 유지하기 위해 쿠키(Cookie)나 세션(Session) 같은 별도의 기술이 필요합니다.

3. REST API의 6가지 핵심 원칙

REST는 HTTP를 기반으로 하지만, 단순히 HTTP를 쓰는 것만으로 RESTful하다고 할 수 없습니다. REST는 다음과 같은 6가지 원칙을 지킬 때 진정한 RESTful 아키텍처가 됩니다.

  • 1. 클라이언트-서버 구조 (Client-Server)

    • 클라이언트와 서버의 역할이 명확하게 분리되어 있습니다. 클라이언트는 UI와 사용자 요청을 담당하고, 서버는 비즈니스 로직과 데이터 관리를 담당합니다. 서로 의존성을 가지지 않고 독립적으로 개발하고 확장할 수 있습니다.

  • 2. 무상태성 (Stateless)

    • REST는 HTTP의 비상태성 원칙을 그대로 따릅니다. 서버는 클라이언트의 상태를 저장하지 않습니다. 모든 요청은 그 자체로 필요한 모든 정보를 담고 있어야 합니다. 이 덕분에 서버의 부담이 줄어들고, 여러 서버를 활용한 부하 분산(Load Balancing)이 쉬워집니다.

  • 3. 캐시 가능 (Cacheable)

    • HTTP가 제공하는 캐싱 기능을 적용할 수 있어야 합니다. 클라이언트는 이전에 받은 응답을 캐시(저장)하여, 동일한 요청이 다시 올 경우 서버에 다시 요청하지 않고 캐시된 데이터를 사용할 수 있습니다. 이는 네트워크 트래픽을 줄이고 응답 속도를 향상시킵니다.

  • 4. 계층화 (Layered System)

    • 클라이언트는 서버에 직접 연결되었는지, 혹은 중간에 프록시나 로드 밸런서 같은 다른 계층이 있는지 알 필요가 없습니다. 모든 요청은 동일한 방식으로 처리됩니다. 이 덕분에 시스템의 유연성과 확장성이 높아집니다.

  • 5. 인터페이스 일관성 (Uniform Interface)

    • 이것이 REST의 가장 핵심적인 원칙입니다.

      • 리소스 식별 (Identification of Resources): 모든 리소스는 URI로 고유하게 식별됩니다.

      • 표현을 통한 리소스 조작 (Manipulation of Resources through Representations): 클라이언트는 리소스의 표현(JSON, XML 등)을 서버에 전송하여 리소스를 조작합니다.

      • 자기 서술적 메시지 (Self-descriptive Messages): 요청과 응답 메시지는 그 자체로 모든 정보를 담고 있습니다. 예를 들어, 응답에 상태 코드와 헤더 정보만 봐도 어떤 결과인지 알 수 있습니다.

      • HATEOAS (Hypermedia as the Engine of Application State): 애플리케이션의 상태 변화가 하이퍼링크를 통해 이루어져야 합니다. (가장 구현하기 어렵고, 실제로는 많이 생략되는 원칙이기도 합니다)

  • 6. 주문형 코드 (Code-On-Demand, 선택 사항)

    • 서버가 클라이언트에게 실행 가능한 코드를 전송하여 클라이언트의 기능을 확장할 수 있습니다. (예: 자바스크립트 코드) 이는 REST의 선택적 원칙으로, 모든 REST API가 이 원칙을 따를 필요는 없습니다.

4. HTTP와 REST API, 관계의 이해

HTTP와 REST는 종종 혼동되지만, 둘의 관계는 명확합니다.

  • HTTP: 인터넷을 통해 데이터를 주고받는 통신 규약(프로토콜) 자체입니다. “어떻게 말할 것인가”에 대한 규칙을 정의합니다. (예: GET /users HTTP/1.1)

  • REST: HTTP 프로토콜의 기능을 최대한 활용하여 API를 설계하는 아키텍처 스타일 또는 철학입니다. “어떤 내용을, 어떻게 구성해서 말할 것인가”에 대한 가이드라인을 제시합니다.

비유하자면, **HTTP는 모든 사람들이 쓰는 ‘언어’이고, REST는 그 언어를 사용해 글을 쓸 때 지키는 ‘문법’**에 가깝습니다. RESTful API는 HTTP라는 언어의 문법을 따라 잘 정리된 글처럼 의미가 명확하고 이해하기 쉽습니다.

5. 실전 RESTful API 디자인 가이드

RESTful API를 잘 설계하면 API의 가독성과 유지보수성이 높아집니다. 다음은 개발자들이 많이 사용하는 디자인 가이드입니다.

5-1. URI 명명 규칙

  • 동사 대신 명사 사용: URI는 리소스(명사)를 나타내고, 행위(동사)는 HTTP 메서드로 표현합니다.

    • ❌ GET /getUsers (동사 사용)

    • ✅ GET /users (명사 사용, users 리소스의 목록을 가져옴)

    • ❌ POST /createUser

    • ✅ POST /users

  • 복수형 명사 사용: 리소스 컬렉션은 복수형으로 쓰는 것이 일반적입니다.

    • GET /users (모든 사용자 목록)

    • GET /users/123 (ID가 123인 특정 사용자)

  • 계층 구조: 리소스 간의 관계를 명확하게 표현합니다.

    • GET /users/123/posts (사용자 123이 작성한 모든 게시물)

    • GET /users/123/posts/456 (사용자 123이 작성한 게시물 456)

5-2. HTTP 메서드 활용

RESTful API는 HTTP 메서드를 리소스에 대한 CRUD(Create, Read, Update, Delete) 작업과 1:1로 매핑하여 사용합니다.

작업 (CRUD)HTTP 메서드예시 URI설명
생성 (Create)POSTPOST /users새로운 리소스를 생성
조회 (Read)GETGET /users/123리소스 또는 리소스 목록 조회
수정 (Update)PUT 또는 PATCHPUT /users/123리소스의 모든 정보를 갱신 (PUT), 일부만 갱신 (PATCH)
삭제 (Delete)DELETEDELETE /users/123리소스 삭제

5-3. API 버전 관리

API는 계속해서 변화하므로, 하위 호환성을 보장하기 위해 버전 관리가 필수입니다. 일반적으로 URI에 버전을 포함하는 방식을 선호합니다.

  • https://api.example.com/v1/users

  • https://api.example.com/v2/users

5-4. 오류 처리

서버는 요청 처리 실패 시 적절한 HTTP 상태 코드를 반환해야 합니다. 이를 통해 클라이언트는 오류의 원인을 쉽게 파악할 수 있습니다.

  • 2xx : 성공 (예: 200 OK, 201 Created)

  • 4xx : 클라이언트 오류 (예: 400 Bad Request, 401 Unauthorized, 404 Not Found)

  • 5xx : 서버 오류 (예: 500 Internal Server Error)

6. 결론: 왜 HTTP와 REST API를 알아야 하는가

HTTP는 오늘날 인터넷의 작동 방식을 이해하기 위한 기본 지식입니다. 그리고 REST API는 HTTP의 원리를 가장 효과적으로 활용하여 API를 설계하는 방법론입니다. 이 두 가지 개념은 서로 분리될 수 없으며, 현대 웹 및 애플리케이션 개발에서 필수적인 요소입니다.

RESTful API의 원칙을 이해하고 적용하는 것은, 다른 개발자들이 쉽게 이해하고 사용할 수 있는 API를 만들고, 더 나아가 확장 가능하고 유지보수하기 쉬운 시스템을 구축하는 첫걸음입니다.

References

REST HTTP

그래프 뷰

백링크