#53. REST API & GraphQL

이번에 다룰 주제는 REST API와 GraphQL 입니다.
클라이언트와 서버는 HTTP 통신으로 데이터와 각종 자원들을 주고 받는데, 상호간에 약속된 바 없이 요청과 응답을 하면 정확한 데이터 전달이 어려워집니다. REST API와 GraphQL을 통해서 클라이언트-서버 간 원활한 의사소통이 가능해집니다.

1. 서버-클라이언트 네트워크 구조

서버-클라이언트 구조란 데이터를 저장하고 관리하는 서버 부분과 해당 서버에 접속하여 데이터를 열람하는 클라이언트 부분으로 구성된 네트워크 구조를 말한다.

서버와 클라이언트는 1:N 구조로 연결되어 있기 때문에 한 대의 서버에 다수의 클라이언트가 접속해서 서비스를 이용할 수 있는 중앙집중화된 구조이다.

2. Server API란 무엇일까요?

Application Programming Interface의 약자로 클라이언트가 서버에 적절한 요청을 했을 때, 서버는 그에 맞는 응답을 되돌려줍니다. 마치 우리가 음식을 주문하면 그에 맞는 요리를 주방장(DB)에게 전달해 알맞는 음식을 내어서 다시 우리에게 주는 웨이터 와 같은 역할을 합니다.

이러한 서버 API를 만드는 방법론에는 크게 2가지가 있습니다.

3. REST API

웹에서 사용되는 데이터나 자원을 HTTP URI로 표현하고, HTTP 프로토콜을 통해 요청과 응답을 정의하는 방식입니다. HTTP 메서드를 이용해 서버와 통신이 가능합니다.

3-1. 좋은 REST API를 디자인하는 방법

리차드슨의 4단계 REST 성숙도 모델은 다음과 같습니다.
1) HTTP 사용

HTTP 프로토콜을 사용하는 것이 REST API의 출발점입니다. 모든 데이터나 자원은 HTTP URI로 표현하고, HTTP의 메서드를 이용해서 요청할 수 있습니다. 예를 들어, 'GET', 'POST', 'PUT', 'PATCH', 'DELETE' 메서드를 통해 요청하며, CRUD를 구현합니다.
2) 개별 리소스와의 통신 준수
개별 리소스에 맞는 엔드포인트를 사용하고, 요청해서 받은 자원에 대한 정보를 응답으로 전달해야 합니다.
urclass에서 GraphQL에 대한 정보를 보기 위해서는 https://server.urclass.io/graphql 다음과 같은 엔드포인트를 사용할 수 있습니다.
상태 코드: 503 / 상태 코드: 202 와 같이 응답상태도 알려줍니다.
3) HTTP 메서드 원칙 준수
CRUD에 맞게 적절한 HTTP 메서드를 사용하는 것에 중점을 둡니다. 병원진료 예약 및 조희를 예로 들면, 조회(READ)할 때는 'GET'메서드와 query parameter를 사용해서 필요한 리소스를 전달합니다.
예약을 생성(CREATE)할 때는 POST 메서드와 예약자명을 body로 보내면 됩니다. 예약이 완료되면 응답은 201 Created로 클라이언트에 전달합니다.
4) HATEOAS 원칙 준수
(Hypertext As The Engine Of Application State)라는 약어로, 응답에 들어가는 링크 요소에는 다음에 할 수 있는 다양한 액션들을 위해 많은 하이퍼미디어 컨트롤을 포함하고 있습니다. 예약 조회 후에는 그 시간대에 예약을 할 수 있는 링크를 삽입하거나, 예약을 완료한 후에는 예약을 확인할 수 있는 링크를 작성해 넣을 수 있습니다.

위의 4단계를 참고해서 REST API를 작성하면 되지만, 상황에 따라 위의 단계를 못지킬 수도 있습니다. 다양한 가이드라인을 참고해보면 좋겠습니다.

4. GraphQL

모든 데이터가 그래프 형태로 연결되어 있는 관계도에서 Query Language를 사용하여 정보를 주고 받습니다. 쉽게 말하면 API를 위한 쿼리언어입니다.

개념을 읽고 감히 생각해볼 때, Query 키워드를 가지고 있는 자원들이 Tree 구조로 되어 있으면 이 키워드에 대한 자원을 찾기위해 최단거리 찾기 알고리즘인 BFS를 사용하여 빠르게 찾을 수 있고, 그 후에는 구독하는 방식을 통해 빠르게 데이터를 전달할 수 있을 것 같습니다.

REST API의 한계를 해결하기 위해 사용됩니다.
1. Overfetch: 필요 없는 데이터까지 제공함.
2. endpoint가 필요한 정보를 충분히 제공하지 못함.
3. 클라이언트 구조 변경 시 엔드포인트 변경 또는 데이터 수정이 필요함

4-1. GraphQL Keywords

1) Query: 저장된 데이터 가져오기 (REST의 'GET'과 유사)
2) Mutation: 저장된 데이터 수정
- Create
- Update
- Delete
3) Subscription: 특정 이벤트가 발생하면 서버가 대응하는 데이터를 실시간으로 클라이언트에게 전송

4-2. GraphQL의 장점

1) 한 번의 요청으로 원하는 모든 데이터를 받아옵니다.
2) POSTMAN과 비슷한 Playground
3) 정확하게 필요한 정보만 받아올 수 있습니다.
4) 클라이언트 구조 변경에도 지장이 없습니다.

4-3. GraphQL의 단점

1) 캐싱이 REST보다 훨씬 복잡합니다.

• HTTP에서는 각 메서드에 따라 캐싱이 구현되어 있습니다. 그러나, GraphQL은 POST 메서드만을 이용해 요청을 보내기 때문에 각 메서드에 따른 캐싱을 지원받을 수 없습니다. 그래서 Apollo 엔진의 캐싱과 영속쿼리 등이 등장하게 되었습니다.
  2) 고정된 요청과 응답만 필요한 경우에는 RESTful API보다 크기가 커집니다.
  3) Learning Curve가 있어 추가 학습이 권장됩니다.