웹 API 설계, RESTful API

0. 오늘의 배울 것

RESTful API, REST API는 REST를 기반으로 만들어진 API이다!!

API란 application programming interface의 줄임말로, 프로그램들 간의 상호 소통을 돕는 인터페이스, 매개체이다. 쉽게 말하자면 한 프로그램에서 다른 프로그램으로 데이터를 주고 받기 위한 의사소통 방법이다. (여기서 프로그램이란 운영체제, 데이터베이스, 응용 프로그램 등등을 일컫는다.)

비유를 하자면,

손님이 음식을 주문하는데 종업원이 주문을 받아 요리사에게 요청을 전달하는 과정이 있다고 하자. 그리고 요리사가 만든 음식을, 종업원이 손님에게 전달하는 과정도 있다.

1. 손님: 프로그램 A
2. 손님이 음식을 주문: 손님(프로그램 A)가 원하는 데이터를 request 함.
3. 종업원: API
4. 요리사: 프로그램 B

이렇게 말할 수 있다. 즉, 손님(프로그램 A)과 요리사(프로그램 B)가 상호작용 하게 도와주는 매개체가 바로 종업원(API)라는 것이다.

API가 왜 필요한가요? 그냥 손님이 요리사에게 직접 주문하면 안되나요? 왜 종업원이 필요한가요? 라고 질문할 수도 있을 것이다.

예를 들어 하나의 DB 프로그램을 공유하는 A, B, C 세 프로그램이 있다고 해보자, 세 개의 프로그램은 DB에 직접 접근해야 하므로 DB 접속 정보를 알고 있어야 한다.

그런데 만약 DB가 바뀐다든가 DB 접속 정보가 바뀐다면 어떻게 해야 할까? 프로그램 A, B, C 각각에서 DB에 대한 정보값을 바꿔줘야 한다.

이렇게 직접적인 프로그램 간의 연결은, 프로그램 간의 종속성을 높인다.

api를 활용해 통신 규약을 정해둔다면, 한 프로그램이 수정되더라도 다른 프로그램들을 수정할 필요가 없다.

WEB API, 웹 API는 웹 서버와 웹 브라우저 간의 API이다!!

api 종류들은 매우 다양하다!! 그 중에서도 웹 서버와 브라우저 간의 소통을 웹 api라고 한다. 때문에 모든 웹 서비스는 api이지만, 모든 api가 웹 서비스는 아니다.

때문에 웹을 개발할 때, 프론트와 백엔드 개발자가 모여 '프론트 엔드에서 이 url로 이런 리퀘스트를 보내면 백엔드에선 이런 처리를 해서 이런 리스폰스를 보내주는 걸로 정하자!' 이런 식으로 논의를 하여 Web API를 설계한 후 서비스를 개발한다. 즉, Web API 설계란 서비스에서 사용될 모든 url에 대해 각 예상 리퀘스트와 리스폰스의 내용을 정리한다는 것이다.

web api는 회사마다 설계 방식이 다르고 딱히 정해진 룰이 없다. 그렇다고 api를 마구잡이로 아무렇게나 설계해도 되는 것은 아니다. Web API가 잘 설계되었는지에 대한 기준으로는 보통 REST API라는 기준이 사용되고 있으며, 많은 사람들이 Web API를 개발할 대 이 REST API를 준수하여 RESTful 한 API를 만들고자 노력한다.

이번 시간에는 REST API가 무엇인지, 어떻게 하면 Web API 설계를 잘 할수 있을지 알아보자!!

1. REST API

REST API란 개발자들이 web api를 설계할 때 준수하는 가이드라인이다. (표준은 아님.)

REST란?

REST는 representational state transfer (표현적인 상태 이전)의 줄임말이다.

자원을 이름(자원의 표현, 웹에서는 url을 가리킴.) 표시하고, 해당 자원의 상태(정보)를 주고받는 것을 의미한다.

예를 들어 우리가 웹 서핑을 할 때, 우리는 계속해서 웹 페이지를 옮겨다니며 다른 url로 이동하는데 그럴 때마다 웹브라우저는 새로운 화면창을 보여준다. 즉 url이라는 자원의 표현을 통해 해당 자원의 상태를 보여주는 아키텍쳐 스타일이라는 것이다!!

REST 구성 요소

• 자원(Resource): 모든 자원에 고유한 ID가 존재하고, 이 자원은 Server에 존재한다. 웹에서 자원을 구별하는 ID는 HTTP URI이다. 클라이언트는 이 URI를 이용해 자원을 지정하고 해당 자원의 상태(정보)에 대한 조작을 Server에 요청한다.
• 행위(Verb): HTTP Method. HTTP 프로토콜은 GET, POST, PUT, DELETE 와 같은 메서드를 제공한다.
• 표현(Representation of Resource): Client가 자원의 상태(정보)에 대한 조작을 요청하면 Server는 이에 적절한 응답(Representation)을 보낸다. REST에서 하나의 자원은 JSON, XML, TEXT, RSS 등 여러 형태의 Representation으로 나타내어 질 수 있고, 주로 쓰이는 건 JSON 혹은 XML 정도이다.

이 개념을 고안한 컴퓨터 과학자 Roy Fielding은 웹이 갖추어야 할 이상적인 아키텍쳐로 REST architercutre를 제시했다.

REST architecture의 조건

이 REST architecture 이 되기 위해선, 6가지의 조건을 충족해야 한다.

1. Client-Server
2. Stateless
3. Cache
4. Layered System
5. Code on Demand
6. Uniform Interface

1. Client-Server

Client-Server 구조를 통해 클라이언트와 서버의 관심사를 분리 (seperation of concern) 애햐 한다. 여기서 클라이언트는 브라우저가 실행되는 컴퓨터, 서버는 서비스를 제공하는 컴퓨터를 말한다. 이렇게 관심사를 분리하면 클라이언트는 사용자에게 어떻게 화면을 보여줄지, 어떻게 다양한 기기에 호환되게 할지 ui적으로 집중할 수 있고 서버는 서비스 구조와 같은 백엔드적 문제에 집중할 수 있어 독립적인 운영이 가능하다.

2. Stateless

무상태, stateless란 서버가 이전의 모든 리퀘스트와 독립적으로 클라이언트의 요청을 완료하는 통신 방법을 말한다. 클라이언트가 보내는 리퀘스트에 대해 서버는 어떤 맥락 context도 저장하지 않기 때문에 클라이언트가 보내는 리퀘스트는 각각 독립적이며 한 리퀘스트가 다른 리퀘스트에게 영향을 주지 않는다! 때문에 하나의 리퀘스트에는 항상 필요한 모든 정보가 담겨야 한다.

3. Cache

캐시를 사용해 네트워크 비용을 절감해야 한다. server가 리스폰스에 '이 리스폰스를 재활용해도 되는지?' 여부를 담아 client에게 보내준다. 이 때 리스폰스 재활용이 가능한 것을 cacheable이라 한다.

4. layered system

클라이언트와 서버 사이에는 프록시나 게이트웨이 같은 중간 매개 요소를 두고, 보안, 로드 밸런싱 등을 수행할 수 있어야 한다. 이런 중간 매개 요소로 인해 클라이언트와 서버 사이에는 계층형 층 hierarchical layers 가 형성된다. 이게 무슨 말이냐면 클라이언트는 클라이언트와 서버 사이에 있는 다른 중간 매개 요소들과 연결될 수 있으며, 그런 와중에도 여전히 서버로부터 응답을 받을 수 있다는 것이다.

5. code on demand

클라이언트는 받아서 바로 실행할 수 있는 applet이나 script 파일을 서버로부터 받을 수 있어야 한다. (이 조건은 옵셔널이라 꼭 만족하지 않아도 됨!!)

6. uniform interface

클라이언트가 서버와 통신할 때의 인터페이스는 통일되고 규칙적인 모습이어야 한다. 이 룰을 지키기 위해 하위 4자기 조건을 지켜야 하는데 이 조건이 바로 REST API와 연관이 깊은 조건이다!!

1. identification of resource: 자원, 리소스는 웹 상에 존재하는 데이터를 나타내는데, 이 리소스를 uri(uniform resource identifier)로 식별할 수 있어야 한다. 앞에서 말했듯 자원에게는 고유한 id 가 있고 웹에서는 그 id를 uri로 지정한다.

2. manipulation of resources through representation: 클라이언트와 서버 둘 다 리소스를 직접적으로 다루는 게 아니라 리소스의 표현(representation)을 다뤄야 한다. 예를 들어 서버에 어떤 리소스를 요청하면, api가 어떻게 구현됐는지에 따라 클라이언트는 해당 리소스를 html 파일 형식으로 받을 수도 있고 png 파일 형식으로 받을 수도 있다. 즉, 클라이언트는 자원 그 자체를 받는 게 아니라 자원의 표현을 받는다는 것이다. 하나의 리소스에는 여러 개의 표현이 있을 수도 있으며, REST architecture에서는 리소스와 리소스의 표현 이 두 가지 개념을 엄격하게 나누는 것이 특징이다.

3. self-descriptive messages: 각 리퀘스트는 stateless 속성 때문에, 모든 정보가 다 담겨있어야 한다. 즉, 리퀘스트와 리스폰스 모두 그 자체의 정보만으로 모든 걸 해석할 수 있어야 한다.

4. hypermedia as the engine of application state: 웹을 분산 하이퍼미디어 시스템 distributed hypermedia system이라고도 하는데, 이는 텍스트, 이미지, 소리 영상 등 모든 미디어가 하이퍼텍스트처럼 서로 연결됐다는 뜻이다! 즉, 웹은 수많은 컴퓨터에 분산된 형태라는 것. 웹을 하나의 프로그램이라 하면, 서버의 리스폰스에는 현재 상태에서 다른 상태로 이전할 수 있는 링크를 포함하고 있어야 한다. 즉, reponse에는 리소스의 표현과 meta 뿐만 아니라 새로운 상태로 넘어갈 수 있는 링크들도 포함되어야 한다.

rest api는 바로 위의 rest architecture에 부합하는 api를 의미한다. 그리고 rest api를 사용하는 웹 서비스를 restful 서비스라고 한다.

RESTful API를 사용하면 뭐가 좋을까?

1. 확장성
   RESTful한 API는 클라이언트-서버 상호 작용을 최적화하기 때문에 효율적으로 크기 조정할 수 있다. 또한 stateless 기준 덕분에 서버는 과거의 클라이언트 요청 정보를 유지할 필요가 없어 서버 로드를 제거한다. 잘 관리된 캐싱은 일부 클라이언트-서버 상호 작용을 줄일 수 있어 통신 병목 현상을 일으키지 않으면서 확장성을 지원해준다!!

2. 유연성
   RESTful 웹 서비스는 완전한 클라이언트-서버 분리를 지원하며, 각 부분이 독립적으로 발전할 수 있도록 해준다. 즉 서버 애플리케이션의 플랫폼 또는 기술 변경은 클라이언트 애플리케이션에 영향을 주지 않는다! 또한 계층을 나누면 다른 계층에 영향을 주지 않고 해당 계층만 유지보수를 할 수 있어 독립성이 높아진다.

3. 독립성
   REST API는 사용되는 기술과 독립적이다. 즉 어떤 프로그래밍 언어를 쓰든 통신에 영향을 주지 않기 때문에, 프로그래밍을 유지 보수하기 편하다.

RESTful 한 API를 만들려면?

이렇게 많고 복잡한 규약을 하나하나 외우며 지키기는 사실 어렵다. REST 개념을 제안한 Roy 또한 어떻게 RESTful한 api를 구현할 수 있을지 구체적인 내용은 제시하지 않았다. 그렇지만 많은 개발자들이 경험과 지식을 토대로 만든 암묵적인 규칙은 잇다!!

여러 조건들이 있겠지만 그 중에서 조건 4-1 identification of resources를 지키는 두 가지 규칙을 일아보자.

1. url은 리소스를 나타내기 위해서만 사용하고, 리소스에 대한 처리는 메소드로 표현해야 한다. 즉, url에서 리소스에 대한 처리를 드러내면 안된다.

   • 예를 들어 새 직원 정보를 추가하기 위해 멤버의 고유 페이지로 가서 post 메소드로 설정한 request를 보내면 된다. 이 경우 url에는 리소스만 나타났고, 리소스에 대한 처리는 메소드 값인 POST로 나타냈으며 url에 표시되지 않았기 때문에 이 규칙을 준수한 것이다.
   • 만약 members/add url로 새 직원 정보를 리퀘스트로 보낸다면, add라는 리소스 처리가 url에 나타났으니 안된다!!

2. document는 단순 명사, collection은 복수 명사로 표시한다.

   • 하나의 객체로 표현할 수 있는 리소스를 도큐먼트
   • 여러 도큐먼트를 담을 수 있는 리소스를 컬렉션 이라고 한다.
   • 비유하자면 도큐먼트는 파일, 컬렉션은 디렉토리!
   • 만약 멤버 전체의 정보를 조회하려면 url은 .../members 이렇게 복수형이어야 한다.

해당 규칙을 지키면서 url을 생각해본다면 다음 표와 같다.

하나 주의할 점은, 우리가 POST 메소드를 쓸 때 특정 직원의 페이지로 가서 하는 게 아니라 members/ 페이지, 즉 컬렉션 타입의 리소스를 대상으로 작업한다는 것이다! 왜냐면 컬렉션들 중에서 하나의 도큐먼트를 삽입하는 것이기 때문이다. 애초에 어떤 id를 할당받을지도 모르는데 members/id값 페이지로 이동한다는 것도 불가능한 얘기다.

2. 정리

위에서 배운 것 말고도 RESTful API를 만들기 위한 규칙은 많다...
REST API는 기술 면접 단골문제기도 하니까, 다른 규칙들도 더 찾아보고 정리하자.