REST API 완벽 가이드: 개념부터 구현까지

이미지 출처 - https://blog.postman.com/rest-api-examples/

"현대 웹 개발의 핵심 아키텍처, REST API를 제대로 이해하고 활용하는 방법"

목차

• REST란 무엇인가?
• REST API의 기본 개념
• REST 구성 요소
• REST의 특징
• REST API 설계 원칙
• REST의 장단점
• REST API 예시
• REST의 대안 기술
• 결론

REST란 무엇인가?

REST(Representational State Transfer)는 2000년 로이 필딩(Roy Fielding)이 자신의 박사 학위 논문에서 처음 소개한 소프트웨어 아키텍처 스타일입니다. REST는 웹의 기존 기술과 HTTP 프로토콜을 그대로 활용하기 때문에 웹의 장점을 최대한 활용할 수 있는 아키텍처입니다.

가장 단순하게 설명하자면, REST는 자원의 표현을 이용하여 상태를 주고받는 것을 의미합니다. 여기서:

• 자원(Resource): 소프트웨어가 관리하는 모든 것
  • 예: 문서, 이미지, 사용자, 제품, 주문 등
• 표현(Representation): 자원을 나타내기 위한 이름
  • 예: URI(Uniform Resource Identifier)를 통해 자원을 명시

웹 애플리케이션을 개발할 때, 우리는 종종 주문 정보, 사용자 프로필, 제품 목록과 같은 다양한 '자원'을 다룹니다. REST 방식에서는 이러한 자원들을 논리적 URI로 표현하고, HTTP 메서드(GET, POST, PUT, DELETE)를 사용하여 자원을 조작합니다.

REST API의 기본 개념

API란?

API(Application Programming Interface)는 컴퓨터 프로그램 간 정보를 주고받을 수 있도록 하는 일종의 출입구와 같은 역할을 수행합니다. 쉽게 말해, 서로 다른 프로그램이 상호작용할 수 있게 해주는 중간자입니다.

일상 생활의 예를 들자면, API는 레스토랑의 웨이터와 같습니다. 고객(클라이언트)은 웨이터(API)에게 주문(요청)을 하고, 웨이터는 이 주문을 주방(서버)에 전달합니다. 주방에서 음식(데이터)이 준비되면 웨이터는 이를 고객에게 다시 전달합니다.

REST API

REST API는 REST 아키텍처 스타일의 제약 조건을 준수하는 애플리케이션 프로그래밍 인터페이스입니다. 간단히 말해, REST API는 REST 기반으로 구현된 API입니다.

REST API는 다음과 같은 특징을 가집니다:

1. 클라이언트-서버 구조: 자원이 있는 쪽(서버)과 자원을 요청하는 쪽(클라이언트)가 분리되어 있는 구조
2. 무상태(Stateless): 각 요청에 클라이언트의 상태 정보가 저장되지 않음
3. 캐시 처리 가능: HTTP의 캐싱 기능 활용 가능
4. 계층화: 시스템 구조를 여러 계층으로 구성할 수 있음
5. 인터페이스 일관성: URI와 HTTP 메서드를 일관되게 사용

REST 구성 요소

REST API는 다음과 같은 핵심 구성 요소로 이루어져 있습니다:

1. 자원(Resource)

서버에 존재하는 데이터를 의미하며, URI로 표현됩니다.

https://api.example.com/users
https://api.example.com/products/123

2. 행위(Verb)

자원에 대한 동작을 정의하며, HTTP 메서드로 표현됩니다.

3. 표현(Representation)

자원의 상태를 표현하는 형식으로, 대표적으로 JSON과 XML이 있으며, 최근에는 JSON이 가장 널리 사용됩니다.

{
  "id": 123,
  "name": "홍길동",
  "email": "hong@example.com"
}

REST의 특징

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

REST API는 일관된 인터페이스를 제공합니다. 자원에 대한 조작을 수행할 때 항상 같은 방식으로 접근할 수 있어야 합니다.

2. 무상태성(Statelessness)

서버는 클라이언트의 상태를 저장하지 않습니다. 모든 요청은 독립적이며, 이전 요청과 무관합니다. 이는 서버의 확장성을 높이고 구현을 단순화합니다.

3. 캐시 가능성(Cacheability)

HTTP 프로토콜의 캐싱 기능을 그대로 활용할 수 있어, 응답 시간을 줄이고 서버 부하를 감소시킬 수 있습니다.

4. 자체 표현 구조(Self-descriptiveness)

REST API 메시지는 자신을 어떻게 처리해야 하는지에 대한 정보를 포함합니다. 특히 JSON 형식의 메시지는 자기 서술적이어서 이해하기 쉽습니다.

5. 클라이언트-서버 구조(Client-Server Architecture)

클라이언트와 서버는 서로 독립적이며, 각자의 역할이 명확히 분리되어 있습니다.

REST API 설계 원칙

좋은 REST API를 설계하기 위해 다음과 같은 원칙을 따라야 합니다:

1. URI는 정보의 자원을 표현해야 한다

# 좋은 예시
GET /users/123

# 나쁜 예시
GET /get-user-by-id/123

2. 자원에 대한 행위는 HTTP 메서드로 표현한다

# 사용자 정보 조회
GET /users/123

# 새로운 사용자 생성
POST /users

# 사용자 정보 업데이트
PUT /users/123

# 사용자 삭제
DELETE /users/123

3. URI는 직관적으로 설계한다

# 좋은 예시
GET /products
GET /products/123
GET /products/123/reviews

# 나쁜 예시
GET /p
GET /get-prod-info/123

4. 응답 상태는 HTTP 상태 코드로 표현한다

REST의 장단점

장점

1. 플랫폼 독립적: HTTP 프로토콜을 따르는 모든 플랫폼에서 사용할 수 있습니다.
2. 서버와 클라이언트의 분리: 서버와 클라이언트의 역할이 명확하게 분리되어 있어, 각각 독립적으로 개발할 수 있습니다.
3. 테스트 용이성: CURL, Postman과 같은 도구를 사용하여 쉽게 API를 테스트할 수 있습니다.
4. 캐싱 가능: HTTP 캐싱을 활용하여 성능을 향상시킬 수 있습니다.
5. 확장성: 기존 API를 변경하지 않고도 새로운 기능을 추가할 수 있습니다.

단점

1. 요청-응답 패턴만 지원: 실시간 양방향 통신이 필요한 경우 적합하지 않을 수 있습니다.
2. HTTP 메서드 제한: 복잡한 행위를 표현하기 어려울 수 있습니다.
3. 오버페칭/언더페칭 문제: 클라이언트가 필요한 데이터만 정확히 가져오기 어려울 수 있습니다.
4. N+1 문제: 여러 자원을 한 번에 가져오기 위해 여러 번의 요청이 필요할 수 있습니다.

JSON 사용의 장단점

REST API는 주로 JSON 형식으로 데이터를 전송합니다. 이에 따른 장단점은 다음과 같습니다:

장점

• 자기 서술적: 데이터 구조를 이해하기 쉽습니다.
• 유연성: 클라이언트가 필요한 필드만 선택하여 사용할 수 있습니다.
• 하위 호환성: 새로운 필드를 추가해도 기존 클라이언트에 영향을 주지 않습니다.

단점

• 메시지 크기: 텍스트 기반이라 이진 형식보다 메시지 크기가 클 수 있습니다.
• 네트워크 효율성: 큰 메시지는 더 많은 네트워크 트래픽을 사용합니다.
• 파싱 오버헤드: JSON 파싱 과정에서 추가적인 CPU 사용이 발생할 수 있습니다.

REST API 예시

실제 REST API가 어떻게 설계되는지 간단한 사용자 관리 API 예시를 통해 살펴보겠습니다:

사용자 관리 API

1. 사용자 목록 조회

GET /api/users

응답 예시:

{
  "users": [
    { "id": 1, "name": "홍길동", "email": "hong@example.com" },
    { "id": 2, "name": "김철수", "email": "kim@example.com" }
  ],
  "total": 2
}

2. 특정 사용자 조회

GET /api/users/1

응답 예시:

{
  "id": 1,
  "name": "홍길동",
  "email": "hong@example.com",
  "created_at": "2023-08-01T12:00:00Z"
}

3. 새 사용자 생성

POST /api/users

요청 본문:

{
  "name": "이영희",
  "email": "lee@example.com",
  "password": "secure123"
}

응답 예시:

{
  "id": 3,
  "name": "이영희",
  "email": "lee@example.com",
  "created_at": "2023-08-15T09:30:00Z"
}

4. 사용자 정보 수정

PUT /api/users/3

요청 본문:

{
  "name": "이영희",
  "email": "newemail@example.com"
}

5. 사용자 삭제

DELETE /api/users/3

응답 예시:

HTTP/1.1 204 No Content

REST의 대안 기술

REST가 모든 상황에 적합한 것은 아닙니다. 상황에 따라 다음과 같은 대안 기술을 고려할 수 있습니다:

1. GraphQL

GraphQL은 클라이언트가 필요한 데이터를 정확히 지정할 수 있게 해주는 쿼리 언어입니다. REST의 오버페칭/언더페칭 문제를 해결하고, 단일 요청으로 여러 자원을 가져올 수 있습니다.

query {
  user(id: "123") {
    id
    name
    posts {
      title
      comments {
        text
      }
    }
  }
}

2. gRPC

Google에서 개발한 고성능 RPC(Remote Procedure Call) 프레임워크로, 프로토콜 버퍼를 사용하여 이진 직렬화를 제공합니다. 높은 성능이 요구되는 마이크로서비스 환경에 적합합니다.

3. WebSocket

실시간 양방향 통신이 필요한 채팅 애플리케이션, 실시간 대시보드 등에 적합한 프로토콜입니다.

결론

REST API는 웹의 기존 인프라를 그대로 활용하면서도 확장성 있는 시스템을 구축할 수 있게 해주는 강력한 아키텍처 스타일입니다. 자원을 URI로 표현하고, HTTP 메서드를 통해 CRUD 연산을 수행하는 단순하지만 효과적인 접근 방식은 웹 개발의 표준으로 자리 잡았습니다.

그러나 REST가 모든 문제를 해결해주는 만능 해결책은 아닙니다. 실시간 통신이 필요하거나, 복잡한 데이터 관계를 다루어야 할 때는 GraphQL, gRPC, WebSocket 등의 대안 기술을 고려해볼 수 있습니다.

최근 트렌드는 REST API를 기본으로 하되, 특정 기능에 따라 다른 기술을 함께 활용하는 하이브리드 접근 방식이 늘어나고 있습니다. 개발자는 각 프로젝트의 요구사항과 제약 조건을 고려하여 적절한 기술을 선택해야 합니다.

REST API를 올바르게 설계하고 구현한다면, 확장성 있고 유지보수가 용이한 웹 서비스를 구축할 수 있을 것입니다.

참고 자료

• RESTful Web Services - Richardson and Ruby
• REST API 설계 가이드 - Microsoft
• Roy Fielding의 REST 논문
• 모질라 개발자 네트워크(MDN) HTTP 문서
• RESTful API 설계 모범 사례