REST API란 무엇인가요?

먼저, REST란 Representational State Transfer를 의미합니다. REST API는 REST 아키텍처 스타일을 준수하여 만들어진 API를 말합니다.

REST 아키텍처 스타일이란 무엇인가요?

💡 Representational State Transfer(REST)는 API 작동 방식에 대한 조건을 부과하는 소프트웨어 아키텍처 스타일입니다. REST는 처음에 인터넷과 같은 복잡한 네트워크에서 통신을 관리하기 위한 지침으로 만들어졌습니다.

REST 기반 아키텍처 스타일을 사용하여 대규모의 고성능 통신을 안정적으로 지원할 수 있습니다. 쉽게 구현하고 수정할 수 있어 모든 API 시스템을 파악하고 여러 플랫폼에서 사용할 수 있습니다.

REST 아키텍처 스타일을 구현하는 웹 서비스를 RESTful 웹 서비스라고 합니다. RESTful API라는 용어는 일반적으로 RESTful 웹 API를 나타냅니다. REST 아키텍처 스타일을 준수하기 위해서는 아래와 같은 원칙을 지켜야합니다.

REST 아키텍처 스타일의 6가지 원칙

  • 클라이언트 / 서버 분리
    • 서로 커뮤니케이션하는 클라이언트와 서버, 가령 모바일 애플리케이션의 동작 방식과 API를 제공하는 서버의 동작 방식에 대해 분리해서 생각해야 합니다.
  • 스테이트리스
    • 리퀘스트를 처리하는데 필요한 모든 정보는 해당 리퀘스트에 포함되어 있어야 합니다.
    • 서버는 리퀘스트를 처리하는데 필요한 클라이언트의 그 어떤 컨텍스트도 서버의 세션에 담지 않습니다.
  • 캐시 가능성
    • 리퀘스트에 대한 리스폰스는 저장 가능 여부(클라이언트가 동일한 요청을 다시 하지 않고 재사용할 수 있도록) 및 기간을 표시해야 합니다.
  • 레이어드 시스템
    • 클라이언트가 서버의 상호작용을 할 때, 오직 서버만을 알고 있어야 합니다.
    • 서버를 이루는 인프라스트럭쳐는 계속 뒷단에 숨겨져 있어야 합니다.
    • 클라이언트는 오직 시스템에서 하나의 레이어만 볼 수 있어야 합니다.
  • 코드 온 디맨드
    • 서버는 필요하다면 클라이언트에 실행 가능한 코드를 전송할 수 있어야 합니다. 이 제약사항은 선택적입니다.
  • 유니폼 인터페이스
    • 모든 상호작용은 식별된 리소스의 개념에 따라 이루어져야 합니다.
    • 이는 식별한 리소스의 조작은 리소스의 상태 표현들과 표준 메서드들을 통해서만 이뤄짐을 의미합니다.
    • 상호작용은 리소스의 표현이 무엇을 의미하는지와 이 리소스들로 무엇을 할 수 있는지 알려줄 수 있는 모든 메타데이터를 제공해야 합니다.

API 목표를 어떻게 REST API로 바꿀 수 있을까요?

API 목표를 REST API를 전환하려면 아래 과정을 거쳐야합니다.

  1. 리소스를 관계를 통해 식별해야 합니다.
  2. 액션과 파라미터, 반환값을 식별해야 합니다.
  3. 리소스 경로를 디자인 해야 합니다.
  4. HTTP를 이용한 리퀘스트 액션을 디자인해야 합니다.

코드숨 예약 시스템 중 ‘좌석을 예약한다’라는 목표를 가지고 예시를 들어보겠습니다. 먼저 주요 동사가 적용될 명사를 나열해 리소스를 식별해야 합니다. ‘예약한다’가 주요 동사이고, 동사가 적용될 명사는 ‘좌석’입니다. 이때 ‘좌석’이 바로 리소스입니다.

그 다음은 액션과 파라미터 그리고 반환값을 식별해야 합니다. 액션은 주요 동사이고 목표의 핵심 리소스에 영향을 줍니다. ’예약한다’가 액션이 되고, 이는 목표의 핵심 리소스인 ‘좌석’을 추가하는 데에 영향을 줍니다. 그리고 좌석 추가하기가 적용될 때 입력으로 좌석 번호가 필요하고, 예약 정보가 출력됩니다.

액션에서 파라미터와 반환값을 식별해보았습니다. 이제 리소스 경로를 디자인해보겠습니다. 리소스는 경로로 식별하기 때문에 유일해야합니다. 좌석이라는 리소스를 식별하기 위해서 경로 /seats/{seatId} 로 표현하겠습니다.

이제 좌석 리소스에 액션을 추가해보겠습니다. HTTP로 표현한 좌석 예약의 목표는 POST /seats 입니다. HTTP 메서드인 POST는 리소스의 생성을 의미하기 때문입니다. 이때 반환되는 리소스는 /seats/{seatId}와 같은 경로로 접근가능해야 합니다.

예약한 좌석 정보를 가져오는 액션의 리소스는 GET /seats/1 가 될 것입니다.

💡 이렇게 표현되기 어려울 때는 절충안으로 액션 그 자체를 리소스로 만드는 방법을 고려할 수 있습니다.

실제로 관리자가 좌석을 추가한다는 목표를 위 과정에 따라 표현해본다면 POST /seats/{seatId} 가 됩니다. 그러면 ‘좌석 예약’을 표현한 리소스 경로와 충돌합니다. 이런 경우에는 예약이라는 액션 자체를 리소스로 만들 수 있습니다. 그러면 POST /seats/{seatId}/reserve 와 같이 표현할 수 있겠죠.

액션 리소스는 명사로 표현되지 않습니다. 액션을 표현하는데는 동사가 쓰인다는 것을 명심하시기 바랍니다. 즉, 액션 리소스는 함수를 표현한다고 보면 됩니다. 액션 리소스를 클래스에 속한 함수처럼 생각하고 보면, 리소스의 하위 리소스로 표현할 수 있습니다.

API 데이터는 어떻게 디자인 해야 하나요?

사용자 관점으로 디자인되도록 주의를 기울여야 합니다. 사용자가 반드시 데이터를 이해하도록 만드는 동시에 내부 동작 원리를 노출하지 않는 디자인을 만드는 것이 중요합니다.

먼저 데이터 구조에 포함되는 속성들을 나열하고 이름을 부여한 뒤, 개별 속성을 사용자가 이해할 수 있는지, 사용자가 관심을 두는지, 실제로 사용자에게 쓸모있는 정보인지 판단해야 합니다.

각 속성들에 대해 다음과 같은 특성을 수집해야 합니다.

  • 이름
  • 타입
  • 필수 여부
  • 필요한 경우 부가 설명

가장 중요한 속성은 이름입니다. 보다 자신을 잘 설명하는 이름일수록 더 좋은 이름입니다.

각 속성의 타입도 분명히 해야 합니다. 이름과 타입은 프로그래밍 인터페이스를 디자인할 때 속성으로 수집할 수 있는 가장 분명한 정보이며, 종종 이름과 타입만으로는 반영하기 어려울 때는 추가 정보로 설명을 더 하면 효과적입니다. API는 하나만 만들어도 여러 언어로 작성된 소프트웨어에서 소비할 수 있기 때문에 되도록 기본 데이터 타입을 써서 여러 프로그래밍 언어에서 지원할 수 있도록 해주어야 합니다.

속성 이름과 유형을 아는 것 외에도 이 속성이 항상 존재해야 하는지도 알아야 합니다. 속성이 필수적인지 또는 선택적인지 나타내는 것은 사용자와 제공자 컨텍스트 양쪽 모두에게 매우 중요합니다.

또한 상품을 추가하고, 수정하고, 또는 교체할 때 상품 정보의 일부를 파라미터로 전달해야합니다. 파라미터는 반드시 필요한 데이터만을 제공해야 하고 불필요한 정보는 제공해서는 안 됩니다. 또한, 백엔드가 자체적으로 처리할 수 있는 데이터를 포함해서도 안 됩니다.

사용자는 반드시 필요한 데이터를 모두 제공할 수 있어야합니다. 사용자 스스로 모든 정보를 알지 못하더라도 다른 API를 통해서 필요한 정보를 얻어올 수 있어야 합니다. 만약 데이터가 제공되지 않는다면, 목표를 놓쳤거나 프로바이더 관점이 남아있을 가능성이 높습니다. 따라서 사용자에게 필요한 모든 데이터가 제공 되는지 확인해야 합니다.

출처