REST(설계 원칙, 리소스 처리)

REST와 RESTful?

• REST: 아키텍처 스타일과 설계 원칙을 정의한 것
• RESTful: REST 아키텍처의 설계 원칙을 준수하는 시스템이나 서비스

REST(Representational State Transfer)는 2000년 Roy Fielding의 박사 논문에서 처음 소개된 소프트웨어 아키텍처 스타일입니다. REST는 웹의 구조를 효율적으로 활용하기 위한 규칙과 원칙을 정의하며, 클라이언트와 서버 간의 상호작용을 단순화하고 확장 가능하도록 설계되었습니다.

RESTful은 REST의 설계 원칙을 준수하여 API를 설계하고 구현한 시스템이나 서비스를 의미합니다. 과연 여기서 REST의 설계 원칙은 무엇일까요?

---

REST 설계 원칙 6가지

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

• 관심사의 분리를 통한 독립적 개발 가능
• 클라이언트와 서버가 관심사에 따른 기능을 나누어 독립적으로 발전할 수 있음
• 사용자 인터페이스 문제(클라이언트)와 데이터 저장 문제(서버)를 분리하여 개선할 수 있음
• ex) 식당에서 손님(클라이언트)과 주방(서버)은 각각의 운영 방식과 식사 방식을 몰라도 됨

2. 무상태성 (Stateless)

• 클라이언트에서 서버로 보내는 각 요청은 이전 요청과 관계없이 독립적으로 처리
• 서버는 클라이언트의 상태를 저장하지 않음
• 모든 요청은 필요한 모든 정보를 포함해야 함
• 따라서 클라이언트 애플리케이션은 세션 상태를 유지해야 함
• ex) 식당에서 예전 손님(클라이언트)은 매번 새로운 손님처럼 누구인지, 어떤 메뉴를 먹을 건지 매번 필요한 모든 정보를 포함해서 요청

3. 캐시 가능성 (Cacheable)

• 서버 응답 시간 개선을 위해 클라이언트는 캐싱(일부 응답 저장 프로세스)을 지원
• 응답은 캐시 가능 여부를 명시하고 동일한 요청이 들어오면 저장한 응답 데이터 재사용
• 효율적인 캐시는 서버 부하 감소와 성능 향상에 기여
• 자주 사용하는 데이터는 저장해두고 재사용
• ex) 자주 주문하는 메뉴는 메뉴판에 미리 적어두기

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

• 클라이언트의 요청을 이행하기 위해 함께 작동하는 여러 계층이 서버에서 실행될 수 있도록 설계
• 계층적 시스템 아키텍처에서 클라이언트는 이런 여러 계층을 알 수 없음
• 시스템의 복잡성을 숨기고 단순하게 사용 가능
• ex) 손님 → 매장직원 → 창고직원 → 물류센터: 손님은 물류센터의 존재를 몰라도 됨

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

1. 리소스(자원) 식별
   • 인터페이스는 클라이언트와 서버 간 상호작용에 관련된 각 리소스(자원)를 식별해야 함
   • 리소스와 메시지(문서)는 분리되어 있어야 함
   • 각 리소스는 고유한 URI(like 리소스의 주소(위치))를 가짐
   • 예: /products/1, /users/123
2. 메시지를 통한 리소스 조작
   • 클라이언트가 리소스의 메시지 보유 -> 메시지를 통해 서버에서 리소스 상태 수정
   • 리소스 수정을 위한 충분한 정보 포함
   • 각 주소(URI)에 대해 할 수 있는 작업들(리소스)를 HTTP 메서드로 처리
   • ex) GET /products/1 → 상품 정보 조회, POST, PUT, DELETE
3. 자기 서술적 메시지
   • 각 리소스 메시지는 자신을 처리하는 방법에 대한 설명을 충분히 전달해야 함

     {
         "type": "product",
         "id": 1234,
         "name": "맛있는 사과",
         "actions": {
             "구매하기": "/products/1234/purchase",
             "장바구니담기": "/cart/add/1234"
         }
     }

4. HATEOAS(Hypermedia as the engine of application state)
   • 애플리케이션의 상태는 하이퍼링크를 통해 다른 모든 리소스와 상호 작용을 동적으로 구동
   • 현재 상태에서 가능한 다음 작업들을 링크로 제공
   • ex) 결제완료 → [배송조회하기, 리뷰 쓰기]

6. 코드 온 디맨드 (Code on Demand) (선택 사항)

• 서버는 소프트웨어 프로그래밍 코드를 클라이언트에 전송하여 클라이언트 기능을 일시적으로 확장하거나 사용자 지정
• 따라서 사전 구현해야 하는 기능이 줄어들어 클라이언트를 간소화할 수 있음
• 필요할 때 기능 추가

---

REST와 리소스

리소스 (Resources)?

리소스(자원)는  HTTP 요청의 대상이며, 쉽게 말해 서비스에서 제공하는 모든 것이라고 생각할 수 있습니다. 예를 들어, 쇼핑몰 서비스가 있으면 상품, 결제, 장바구니 등은 모두 리소스라고 할 수 있습니다. 이런 리소스는 REST의 정보 추상화에 핵심이라고 할 수 있습니다.

 

리소스 표현(resource representation)은 특정 시점에 해당 리소스의 상태를 나타내는 것입니다. 이런 리소스 표현은 아래와 같은 3가지로 구성됩니다.

• 데이터: 실제 리소스 내용
• 메타데이터: 데이터를 설명하는 데이터, 설명 정보
• 하이퍼미디어 링크: 클라이언트가 다음에 원하는 상태로 전환하는 데 도움 (like 내비게이션: 현재 위치 -> 다음 작업 안내)

REST로 리소스 표현을 효과적으로 다루기 위한  3가지 원칙

• REST: 리소스를 주고받기 위한 규칙
• 리소스: 자원, 업무에 필요한 모든 요소

REST는 웹에서 리소스를 주고받기 위한 규칙을 정의한 것입니다. REST는 리소스 표현의 각 구성요소를 효과적으로 다루기 위한 원칙을 제공합니다. 아래에서 설명하는 세 가지 개념은 REST에서 리소스를 다루는 핵심 원칙들입니다.

 

1. 리소스 식별자 (Resource Identifiers): 리소스 어떻게 찾을지 

클라이언트와 서버 사이의 상호작용에서 각 리소스를 식별하기 위해 식별자를 사용합니다. 

 

2. 하이퍼미디어 (Hypermedia): 리소스와 관련된 다음 작업을 어떻게 안내할지

데이터 형식을 미디어 타입이라고 하며, 이 미디어 타입은 데이터를 어떻게 처리해야 할지 알려줍니다.

 

3. 자기 설명적 (Self-Descriptive): 리소스를 어떻게 처리할지

클라이언트는 리소스가 무엇인지 미리 알 필요 없이, 받은 데이터의 미디어 타입만 보고도 어떻게 처리해야 할지 알 수 있어야 합니다.

{
    // 1. 리소스 식별자: 리소스를 찾기 위한 정보
    "id": "product_1234",
    "url": "/products/1234",

    // 데이터 (실제 리소스 내용)
    "name": "맛있는 사과",
    "price": 3000,
    
    // 메타데이터 (데이터 설명)
    "created_at": "2024-01-18T10:00:00Z",
    "version": "1.0",
    "_type": "application/vnd.shop.product+json",  // 3. 자기 설명적 요소
    
    // 2. 하이퍼미디어 링크: 다음 작업 안내
    "_links": {
        "구매하기": "/products/1234/purchase",
        "장바구니": "/carts/add/1234"
    }
}

 

REST의 리소스 메서드

리소스 메서드는 리소스의 한 상태에서 다른 상태로 전환하는 데 사용되는 방법들입니다.

 

REST는 HTTP 메서드(GET/PUT/POST/DELETE)를 정확히 지정된 용도로만 사용해야 한다는 오해가 있지만, 중요한 건 서비스 전체에 일관된 방식(uniform interface)으로 사용해야 합니다. 예를 들어, 회사 A에서 사용하는 API는 일반적인 HTTP 메서드 방식과 다르지만, 회사 A안에서 정한 방식으로 일관적이게 API 만든다면 문제 될 게 없는 겁니다. 또한 회사 A와 회사 B의 방식이 달라도 일관적이라면 각각 REST에 부합하다고 할 수 있습니다.

 

이러한 일관성의 원칙은 API 응답에도 적용됩니다. API가 리소스의 현재 상태를 반환할 때는 해당 리소스에 대해 수행할 수 있는 모든 작업도 함께 알려주어야 합니다. 예를 들어, 주문 상태가 '배송 준비 중'일 때는 '배송 시작', '주문 취소' 등의 가능한 작업을 함께 반환하고, '배송 완료' 상태일 때는 '리뷰 작성', '반품 신청' 등의 가능한 작업을 반환해야 합니다. 따라서 리소스의 표현에는 현재 상태뿐만 아니라 가능한 모든 상태 전환(리소스의 상태를 변경하는 모든 작업) 방법도 포함되어야 합니다.

 

---

마치며

REST는 단순하지만 강력한 아키텍처 스타일로, 효율적이고 유지보수 가능한 시스템을 설계할 수 있습니다. 하지만 실무에서는 RESTful 설계 원칙을 모두 준수하면서 개발하는 것은 현실적으로 어렵다고 합니다. 실무에서는 HTTP API나 REST API를 비슷한 의미로 사용한다고 하지만, 실제로 REST API를 설계하기 위해서는 위에 있는 모든 조건을 지켜야 합니다. 따라서 상황에 따라 REST를 적절하게 이용하는 것이 중요합니다.

---

[참고자료]

• https://restfulapi.net/
• https://aws.amazon.com/ko/what-is/restful-api/