시스매

REST API, 웹 통신의 혁명 핵심 원리와 사용법 완벽 가이드

12 min read

2025-08-11 21:56

Tags:

REST API, 웹 통신의 혁명: 핵심 원리와 사용법 완벽 가이드

“웹(Web)의 잠재력을 최대한 활용하라.” 2000년, 로이 필딩(Roy Fielding)은 이 한 문장으로 REST(Representational State Transfer) 라는 개념을 세상에 내놓았습니다. 당시 웹은 복잡하고 비효율적인 통신 방식으로 성장의 한계에 부딪히고 있었습니다. 필딩은 웹 본연의 장점을 살린, 단순하고 확장성 높은 아키텍처 스타일을 제안했고, 이는 현대 웹 개발의 표준으로 자리 잡았습니다.

이 핸드북은 REST가 무엇인지, 왜 만들어졌는지, 그리고 어떻게 사용하는지에 대한 모든 것을 담고 있습니다. 개발자뿐만 아니라 웹의 동작 원리를 이해하고 싶은 모든 분들에게 훌륭한 안내서가 될 것입니다.

1. REST, 왜 만들어졌을까? (탄생 배경)

REST가 등장하기 이전, 웹 애플리케이션 간의 통신은 주로 SOAP(Simple Object Access Protocol) 와 같은 복잡한 프로토콜에 의존했습니다. SOAP는 강력한 기능을 제공했지만, 다음과 같은 문제점을 안고 있었습니다.

  • 높은 복잡도: XML 기반의 엄격한 규칙과 방대한 표준으로 인해 배우고 사용하기 어려웠습니다.

  • 무거운 데이터 구조: 통신 시 불필요한 정보가 많이 포함되어 성능 저하를 유발했습니다.

  • 플랫폼 종속성: 특정 플랫폼이나 프로그래밍 언어에 종속되는 경우가 많아 유연성이 떨어졌습니다.

로이 필딩은 이러한 문제들을 해결하고, 웹의 창시자인 팀 버너스리가 구상했던 하이퍼미디어 기반의 분산 시스템이라는 웹의 기본 철학을 되살리고자 했습니다. 그는 HTTP 프로토콜의 장점을 최대한 활용하여, 특정 기술에 얽매이지 않고 누구나 쉽게 이해하고 사용할 수 있는 간결한 통신 방식을 고안했습니다. 이것이 바로 REST입니다.

비유: 복잡한 서류 양식과 절차를 거쳐야 했던 관공서 업무(SOAP)를, 정해진 창구에서 간단한 신청서만으로 처리할 수 있는 시스템(REST)으로 바꾼 것에 비유할 수 있습니다.

2. REST의 핵심 구조: 6가지 원칙

REST는 ‘프로토콜’이나 ‘표준’이 아닌, 아키텍처를 설계하는 ‘스타일’ 또는 ‘원칙’ 입니다. 이 6가지 원칙을 모두 지켜야 진정한 ‘RESTful’하다고 할 수 있습니다.

  1. 클라이언트-서버 (Client-Server):

    • 정의: 사용자 인터페이스를 담당하는 클라이언트와 데이터를 관리하는 서버의 역할을 명확하게 분리합니다.

    • 이유: 서로의 의존성을 낮춰 독립적인 개발과 확장이 가능해집니다. 예를 들어, 서버 교체 없이 모바일 앱(클라이언트)을 추가로 개발할 수 있습니다.

  2. 무상태 (Stateless):

    • 정의: 서버는 클라이언트의 상태를 저장하지 않습니다. 각 요청은 독립적으로 처리되며, 필요한 모든 정보는 요청 자체에 포함되어야 합니다.

    • 이유: 서버의 부담을 줄이고, 어떤 서버로 요청이 전달되더라도 동일한 응답을 보장할 수 있어 확장성(Scalability)을 높입니다.

    • 예시: 로그인 상태 유지를 위해 서버가 세션을 저장하는 대신, 클라이언트가 매 요청마다 인증 토큰(JWT 등)을 보내는 방식입니다.

  3. 캐시 가능 (Cacheable):

    • 정의: 클라이언트는 서버의 응답을 캐시(임시 저장)할 수 있어야 합니다. 서버는 응답 데이터가 캐시 가능한지 여부를 명시해야 합니다.

    • 이유: 동일한 요청에 대해 서버에 다시 접근할 필요 없이 캐시된 데이터를 사용함으로써 성능을 향상시키고 서버 부하를 줄입니다.

  4. 계층화 시스템 (Layered System):

    • 정의: 클라이언트는 최종 서버에 직접 연결되는지, 중간의 프록시 서버나 로드 밸런서를 거치는지 알 필요가 없습니다. 각 계층은 독립적인 기능을 수행합니다.

    • 이유: 보안 강화, 로드 밸런싱, 암호화 등 다양한 기능을 추가하거나 변경하기 용이해져 시스템 전체의 유연성이 높아집니다.

  5. 균일한 인터페이스 (Uniform Interface):

    • 정의: 특정 아키텍처에 얽매이지 않고, HTTP 표준만 따른다면 어떤 플랫폼에서든 통신할 수 있도록 하는 가장 핵심적인 원칙입니다. 4가지 하위 원칙으로 구성됩니다.

      • 자원의 식별 (Identification of resources): 모든 자원(Resource)은 URI(Uniform Resource Identifier)를 통해 고유하게 식별되어야 합니다. (예: /users/123)

      • 표현을 통한 자원 조작 (Manipulation of resources through representations): 클라이언트는 자원의 ‘표현(Representation)‘(주로 JSON 또는 XML 형식)을 받아 조작합니다.

      • 자기 서술적 메시지 (Self-descriptive messages): 각 메시지는 스스로를 설명할 수 있어야 합니다. 즉, 메시지만 보고도 무엇을 의미하는지 이해할 수 있어야 합니다. (예: Content-Type: application/json)

      • 하이퍼미디어 (HATEOAS: Hypermedia as the Engine of Application State): 클라이언트는 URI를 미리 알고 있을 필요 없이, 서버로부터 받은 응답에 포함된 링크를 통해 다음에 수행할 수 있는 동작을 파악할 수 있어야 합니다.

  6. 주문형 코드 (Code on Demand - Optional):

    • 정의: 서버가 클라이언트에게 실행 가능한 코드(예: JavaScript)를 전송하여 클라이언트의 기능을 일시적으로 확장할 수 있도록 허용합니다.

    • 이유: 모든 기능을 클라이언트에 미리 구현할 필요가 없어 배포를 단순화할 수 있습니다. 하지만 필수적인 원칙은 아닙니다.

3. RESTful API 사용법: 자원과 행위

RESTful API는 ‘자원(Resource)’ 과 ‘행위(Verb)’, 그리고 ‘표현(Representation)’ 이라는 세 가지 요소로 구성됩니다.

  • 자원 (Resource): URI로 표현되는 모든 것. (예: /users, /posts/1)

  • 행위 (Verb): HTTP 메서드를 사용. (GET, POST, PUT, DELETE 등)

  • 표현 (Representation): 자원의 상태를 나타내는 데이터. (주로 JSON 형식)

HTTP 메서드역할 (CRUD)설명
GETRead (조회)특정 자원의 정보를 요청합니다.
POSTCreate (생성)새로운 자원을 생성합니다.
PUTUpdate (전체 수정)특정 자원의 전체 정보를 교체합니다.
PATCHUpdate (부분 수정)특정 자원의 일부 정보만 수정합니다.
DELETEDelete (삭제)특정 자원을 삭제합니다.

좋은 URI 설계 예시:

  • GET /users/1: 1번 사용자의 정보를 조회합니다.

  • POST /users: 새로운 사용자를 생성합니다.

  • PUT /users/1: 1번 사용자의 정보를 수정합니다.

  • DELETE /users/1: 1번 사용자를 삭제합니다.

나쁜 URI 설계 예시:

  • GET /getUserInfo?id=1 (URI에 행위가 포함됨)

  • POST /createUser (URI에 행위가 포함됨)

4. 심화: 성숙도 모델 (Richardson Maturity Model)

레너드 리처드슨(Leonard Richardson)은 RESTful API가 얼마나 REST 원칙을 잘 따르는지를 평가하기 위해 4단계의 성숙도 모델을 제안했습니다.

  • Level 0: The Swamp of POX (Plain Old XML)

    • 단순히 HTTP 프로토콜 위에서 원격 프로시저 호출(RPC)처럼 사용하는 단계. REST의 이점을 거의 활용하지 못합니다.

  • Level 1: Resources

    • 개별 자원(Resource) 개념을 도입하고, 각 자원에 고유한 URI를 부여합니다.

  • Level 2: HTTP Verbs

    • GET, POST, PUT, DELETE 등 다양한 HTTP 메서드를 사용하여 자원에 대한 행위를 명시적으로 표현합니다. 대부분의 ‘REST API’가 이 단계에 해당합니다.

  • Level 3: Hypermedia Controls (HATEOAS)

    • 응답에 다음 행동을 위한 링크를 포함하여, 클라이언트가 동적으로 API를 탐색할 수 있도록 합니다. 가장 성숙하고 이상적인 REST API 단계입니다.

REST는 단순히 기술적인 규약을 넘어, 웹의 본질적인 가치를 되살리고 개발자들이 더 유연하고 확장 가능한 시스템을 만들 수 있도록 돕는 철학에 가깝습니다. 이 핸드북이 여러분의 RESTful한 여정에 든든한 동반자가 되기를 바랍니다.

혹시 REST API를 설계할 때 가장 고민되는 부분은 무엇인가요? 함께 이야기해보면 더 좋은 해결책을 찾을 수 있을 것입니다.

References

REST

그래프 뷰

백링크