자연스러운 궁금증

기본 언어 공부 이후 웹 개발을 한다고 하면 첫 단계에서 배우게 되는 개념이다. Rest API? 아마 많은 분들이 이를 설명할 때 처음에는 그냥 주소에 데이터를 HTTP 메서드에 따라 주거나, 받거나, 주고 받거나 할 때 쓰는 것이라는 정도로 설명하고 일단 그냥 URL이라고 이해하고 넘어가는 경우가 많다. 처음에 그냥 JSON으로 주고 받는 방법만 배우고 나면 일단 사용하는 데 문제는 없기 때문에 개념을 온전히 이해하는 건 나중에 해도 되기 때문이다.

하지만 문제는 프로젝트에서 이미지 데이터와 같이 텍스트 형태 이외의 데이터를 주고 받아야 하는 경우에서 발생한다. 아마 구글링을 통해 주고 받는 방법은 또 알아낼 수 있겠지만 그냥 JSON으로 텍스트 데이터를 주고 받기만 하면 끝나는 게 아니라는 걸 깨닫게 될 때 쯤에는, 다양한 형태의 데이터를 주고 받는 방법에 대한 고민을 자연스럽게 하게 된다. 여기서 조금 더 깊어지면 스스로 사용하던 JSON을 이용한 방법(혹은 그 외의 방법)이 어떻게 작동하고 있었던 것인지에 대한 의문까지 이어지게 되는데, 이 기점에서 Rest API에 대해 공부하게 된다. JSON 형태로 데이터를 주고받는 API 스타일은 RestAPI 외에 GraphQL도 있지만 처음 개발을 공부할 때는 많은 사람들이 RestAPI를 사용하기 때문에 이러한 흐름을 따라갔을 가능성이 높다. 그렇다면 이제 본론이다. Rest API는 무엇인가?

Rest API?

Rest API는 Representational State Transfer Application Programming Interface의 약자다. 거의 문장급으로 긴 단어인데, 하나하나 분석해 보도록 하자.

• Representational : 표현
  Representational은 웹 서비스 내의 각 자원들이 고유한 표현을 갖는다는 의미라고 한다. 고유한 표현? 잘 와닿지 않는다. 조금 더 친절한 설명은, 웹 서비스에서의 자원은 곧 데이터다. 데이터가 고유한 표현을 갖는다는 것은 데이터들이 특정 양식(form)에 담겨 있다는 말이다. 그리고 이 양식을 각 상황에 맞게 설정하면 되는데, 이 양식의 종류에는 JSON이나 XML 등이 있다.

  주로 개발 공부를 하는 단계에서는 직관적으로 이해하기 쉬운 JSON 형식을 이용하기 때문에, REST API를 사용한다고 하면 JSON 형태의 데이터를 주고 받는 것이라고 알고 있는 경우도 많다. 하지만 정확히는 REST API를 사용하는 여러 방식 중 JSON이 가장 직관적이고 REST API에 입문하기에 좋은 형태이기 때문에 많이 쓰는 것 뿐이다.

• State Transfer : 상태 통신
  State Transfer는 의미 그대로 상태 정보를 주고 받는다는 말이다. 상태 정보를 주고 받는 방식은 다른 API 스타일에서도 아마 달리 있겠지만, 적어도 Rest API에서는 HTTP Request와 HTTP Response의 형태로 통신한다. 위에서 Representational의 경우, HTTP 통신 시 body에 관한 설명이고, State Transfer는 Http의 구성 요소인 Start Line, Header, Body를 모두 포함하여 하나의 '상태'로 간주하고 이를 주고 받는다는 것. 그리고 전송 방향이 Client -> Server일 경우 request, 반대의 경우 response인 것이다.

• Application Programming Interface
  API는 세 단어를 묶어서 이해해야 한다. Application은 모든 소프트웨어를 통칭한다. 웹 개발을 하고 배포까지 했다면 어떤 형태로든 서버를 올렸다는 것인데, 이 서버에서 돌리고 있는 모든 프로그램들, 좀 더 구체적으로는 개발자가 제공하는 서비스가 잘 작동하기 위해 가동되고 있는 모든 프로그램들은 모두 Application이다.
  Programming Interface는 사실 Programming보다는 Interface가 더 큰 의미를 갖는다. Interface의 가장 큰 특징은 유연성이다. 아래는 RedHat에서 제공하는 API에 관한 설명글의 일부를 인용한 것이다.

  API를 사용하면 구현 방식을 알지 못하는 제품 또는 서비스와도 통신할 수 있으며 애플리케이션 개발을 간소화하여 시간과 비용을 절약할 수 있습니다.
  ...(중략)
  API는 당사자들 간 계약을 나타내는 도큐멘테이션을 갖춘 계약으로 비유되기도 합니다. 한쪽 당사자가 특정한 방식으로 구성된 원격 요청을 보내면 다른 쪽 당사자의 소프트웨어가 이에 응답하는 방식이기 때문입니다.

  여기서 주목해야 하는 점은, API가 일종의 '계약'과 유사한 형태를 띤다는 점이다. 앞서 Rest API의 경우 request와 response를 주고 받는다고 했다. API 입장에서 Server가 request를 어떻게 처리하는 지 알아야 하는 이유가 있는가? 전혀 없다. 그저 API는 Client가 API에 데이터를 잘 담고, API는 지정된 엔드 포인트로 이를 전달하고, Server는 다시 API에 데이터를 잘 담고, 다시 API는 지정된 엔드 포인트에 전달하기만 하면 된다.

  따라서 이러한 이유로 'Interface'라는 표현이 등장하는 것이다. Interface의 특징은 추상적이고 따라서 유연하다는 것이다. Rest API의 경우 JAVA를 쓰든 Python을 쓰든, HTTP 프로토콜을 따르고 있기만 한다면 이 API에 담긴 '상태'를 받을 구현체를 커스텀할 수 있다. JAVA를 예시로 들면, DTO(Data Transfer Object)로 body에 있는 데이터만 사용할 수도 있고, Spring에서 제공하는 HttpServletRequest 클래스를 통해 Http Request 자체를 그대로 복사한 구현체를 이용할 수도 있다. 핵심은, 통신을 통해 들어온 Request를 프로젝트마다, 개발자마다 Server에서 유연하게 구현체를 생성할 수 있다는 것이다.
  

• Rest API (Relational State Transfer Application Programming Interface)
  이제 Rest API를 요약해 보자. Rest API는 HTTP 프로토콜에 따라 전송되는 데이터가 담긴 '정보 덩어리'이다. 그리고 여기 담기는 정보는 모두 '상태'로 정의된다.

Rest API의 구성과 특징

앞서 Rest API의 개념와 의미에 대해 소개했다. 그렇다면 이제 어떻게 활용해야 하는지 알아볼 차례다. Rest API의 구성과 특징에 대해 알아보자.

Rest API의 구성

Rest API는 아래와 같이 3가지 요소로 구성되어 있다.이를 이르러 REST 아키텍처라고 부른다.

• 자원(Resource) : HTTP URI
• 자원에 대한 행위(Verb) : HTTP Method
• 자원에 대한 행위의 내용 (Representations) : HTTP Body (Pay Load)

먼저 Resource의 경우 왜 HTTP URI인지 이해가 잘 가지 않는다. HTTP URI가 Resource인 이유는 URI 자체가 어떤 데이터를 가리키는지 알 수 있도록 구성되어 있기 때문이다. 예를 들어, users/1과 같은 URI가 있다고 하자. 이는 users 중 Id가 1인 user 데이터를 resource로 사용하겠다는 뜻이다. 따라서 HTTP URI가 Resource로 표현되는 이유는 URI 자체가 '의미'를 내포하고 있기 때문이고, 이 점이 Rest API의 가장 큰 특징으로 이어진다.

다음으로 Verb의 경우 앞서 Resource에 대해 어떠한 행위를 할 것인지를 나타낸다. 이는 납득하기 어렵지 않다. users/1의 데이터를 CRUD와 같은 메서드 중 어떤 작업을 할 것인지를 나타낸다는 것.

마지막으로 Representations의 경우 첫 부분에서 설명했듯이 특정 형태의 데이터를 말한다. 사실 통신에 있어서 contents, data, resource 등등은 비슷하게 해석되기도 하고, 다들 의미를 혼용하는 경우가 많다. 맥락에 따라 Http body를 data로 말하는 사람도 있고, payload를 data로 말하는 사람도 있고, contents로 말하는 사람도 있다. 여기에 있어서 명확한 기준이 있는 지는 잘 모르겠지만, 우선 Rest API에서 Representations는 명백히 Http의 body(pay load)를 말한다.

Rest API의 특징

Rest API의 특징은 사실 검색하면 금방 알 수 있다. 이미 많은 사람들이 정리를 해 놓았는데, 똑같이 정리하기보다는 Chat-gpt에게 물어보고 알려준 답변에 약간씩 부연 설명을 해 보려고 한다.

1. Stateless

REST API는 상태를 서버에 저장하지 않습니다. 각 요청에는 처리에 필요한 모든 정보가 포함되어 있어야 하며, 이를 통해 서버의 확장성이 향상됩니다.

-> 상태를 서버에 저장하지 않는다는 말은 Rest의 s가 State 즉 상태였던 것을 기억하면 이해하기 쉽다. 요청과 응답 자체가 하나의 상태이기 때문에, 상태를 저장하지 않는다는 말은 곧 이전 요청과 응답을 기억하지 않는다는 말이다.
따라서 Client가 요청을 보낼 때는 항상 Client 자체에 대한 정보를 함께 보내야 한다. 이는 수 없이 많은 Client의 트래픽을 감당해야 하는 Server의 부담을 Client로 일부 분산되도록 하여 효율성이 증가한다.

2. Client-Server Architecture

클라이언트와 서버는 독립적으로 존재하며, 서로 작업을 수행할 수 있습니다. 이 구조를 통해 각 구성 요소의 관심사가 분리되어 구현 및 유지 관리가 간소화됩니다.

-> 클라이언트와 서버가 공존하던 때도 있었지만, 이는 이제 분리되었는데, 바로 프론트 엔드와 백 엔드라는 이름으로 분리되었다. 과거에는 개발자 한 명이 HTML, CSS, javascript, Java(와 같은 현재 백엔드 언어로 불리는 언어들)를 모두 다뤘어야 했지만 Rest API와 같은 통신 방법이 등장하면서 더 이상 그러지 않게 되었다는 말.

3. Cacheable

REST API는 클라이언트 측에서 서버로부터 받은 응답을 캐싱할 수 있습니다. 캐싱을 이용해 다음 번 동일한 요청에 대해 더 빠른 응답을 처리하거나 부하를 줄일 수 있습니다.

-> 1번과 상충하는 듯 보이지만 전혀 아니다. 1번은 Server가 저장하지 않는다는 말이고, 이 3번은 Client가 저장한다는 말이다. 토큰 발급을 예시로 들면, 우리는 한 웹 페이지 내부에서 다른 탭을 클릭할 때마다 아이디와 비밀번호를 입력하지 않아도 되도록 토큰이라는 걸 캐싱해 둔다. 따라서 로그인을 통해 한 번 인증된 클라이언트는 해당 토큰을 요청마다 함께 전송해 인증 정보를 재입력하지 않아도 된다는 것.

4. Layered System

REST API는 계층화된 구조를 가질 수 있습니다. 이를 통해 클라이언트는 직접 연결된 서버와만 상호 작용하며, 여러 개의 중간 계층이 있을 수 있습니다. 이러한 설계를 통해 시스템의 유연성과 보안을 향상시킬 수 있습니다.

-> 클라이언트 -> 서버가 아니라 클라이언트 -> 프록시 서버 -> 서버의 형태를 가질 수 있다는 말. 보안에 있어 강점을 가질 수도 있고, 관심사를 분리하여 여러 개의 서버를 구성하거나 블루(blue) - 그린(green) 배포와 같이 로드 밸런싱도 가능하다는 것.

5. Uniform Interface

REST API는 일관된 인터페이스를 제공합니다. 이 특징은 표준 규칙과 규약을 이용해 다양한 클라이언트가 쉽게 사용할 수 있게 해줍니다. 다음과 같은 원칙이 지켜져야 합니다.

• 자원 식별(Resource Identification): URI를 사용해 각 자원을 유일하게 식별합니다.
• 자원 조작을 위한 메서드 지원: HTTP 메서드를 사용해 자원에 대한 작업을 수행합니다 (예: GET, POST, PUT, DELETE).
• 자기 설명적 메시지(Self-descriptive Messages): 메시지는 각 작업에 필요한 정보를 포함합니다.
• HATEOAS(Hypermedia As The Engine Of Application State): 클라이언트는 동적으로 서버에서 제공하는 하이퍼미디어를 이용해 애플리케이션 상태를 변경하고 진행할 수 있습니다.

-> 여기서 표준 규칙과 규약은 곧 HTTP 프로토콜을 말한다. 그리고 일관된 인터페이스를 제공한다는 것은 어느 프로그래밍 언어든 어떤 유형의 서비스든 상관 없이 유사한 구조로 Restful 서비스를 사용할 수 있다는 말이다. 즉 게임 홈페이지든, 쇼핑몰 사이트든, 서버가 RestAPI를 사용하고 있다면 그 설계가 크게 차이나지 않을 것이며 비즈니스 로직만 다를 것이라는 말이다.

그리고 원칙들 중에서는 다른 원칙들은 다 납득이 가지만 HAREOAS가 이해가 어렵다. 말이 굉장히 어려운데 사실 그냥 페이지가 동적이어야 한다는 말 외에 무엇도 아니다. 이 페이지에서 다른 페이지로 이동한다거나 하는 액션이 잘 작동해야 한다는 말.

마치며

알아보자 시리즈 2번째 글이었다. 사실 글을 굉장히 길게 썼고 뭔가 내용도 많이 담아서 있어 보일 수 있지만 잘 뜯어보면 더 추가되면 좋을 설명도 있고 몰라서 설명하지 못한 부분도 더러 있다. GraphQL과 같은 다른 API들과의 차이점이라든지 등등... 아직 공부가 많이 부족하기 때문인 것 같다.

아직 2번째 글밖에 되지 않았는데도 내가 얼마나 그 동안 개념들을 대충 넘겼는지가 체감이 되는 중이다. 하지만 이렇게 시리즈를 계속 이어가다 보면 언젠가 개념에서 구멍난 부분을 상당 부분 메꿀 수 있지 않을까 생각한다.