REST API vs GraphQL

1. Server API

Server API는 적절한 요청을 하였을 때 그에 맞는 응답을 되돌려 주는 창구(Endpoint)를 Web을 통해 노출한 것을 말한다.
이런 Server API는 어떤 정보들을 요청하고 수정하기 위해서 만들어지는 경우가 많다.

이 Server API를 만드는 방법론 중 하나로 REST 라는 것이 있으며,
이 방법론은 많은 Server API들을 구성하기 위해 사용되어왔고, 또 현재 많이 사용하고 있다.

2. REST와 RESTful

2-1) REST 정의

REST는 Representational State Transfer 의 줄임말이다.
모든 Resource를 하나의 Endpoint에 연결해놓고, 각 Endpint는 그 Resource와 관련된 내용만 관리하게 하자는 방법론이다.

즉 자원(resource)의 표현(representation)에 의한 상태 전달
좁은 의미로 HTTP를 통해 CRUD(Creat,Read,Update,Delete)를 실행하는 API를 뜻한다.

2-2) REST 자원

여기서 자원(resource)란 해당 소프트웨어가 관리하는 모든 것이다.
자원의 표현은 그 자원을 표현하기 위한 이름으로 DB의 유저정보가 자원이라면 user를 자원의 표현으로 정한다.

2-3) REST 예시

예시로 어떤 API가 Community site용 API이며, 이 API를 통해 사용자들이 글을 CRUD 할 수 있고 각 댓글에도 작성/수정/삭제 할 수 있다고 가정한다면
이때 API 의 Endpoint 를 다음과 같이 구성하면 REST 의 조건을 간략히는 만족하게 된다

글 관련 API = /posts
글 작성 = POST /posts
글 수정 = PATCH /posts/[postid]
글 삭제 = DELETE /posts/[postid]
댓글 관련 API = /posts/[postid]/comments
댓글 작성 = POST /posts/[postid]/comments
댓글 수정 = PATCH /posts/[postid]/comments/[commentid]
댓글 삭제 = DELETE /posts/[postid]/comments/[commentid]

2-4) RESTful

이런 REST 의 조건을 만족하는 API 를 RESTful API 라고 부르고, 이런 방식으로 API 를 작성하는 것을 RESTful 하다고 한다.

즉 RESTful하다라는 것은 REST API의 설계의도를 명확하게 지켜주는 것이다. '/'를 통해 계층관계를 표시한다던가 숫자는 id를 나타낸다든가 동사보단 명사를 위주로 쓴다든가 하는 등...

2-4) REST 장점과 단점

REST API의 장점

• REST는 기본적으로 웹의 기존 기술과 HTTP 프로토콜을 그대로 활용하기 때문에 웹의 장점을 최대한 활용할 수 있는 아키텍쳐 스타일이다.
• HTTP 프로토콜을 사용하므로 REST API 사용을 위한 인프라를 구축할 필요가 없다.
• HTTP 표준 프로토콜을 따르는 모든 플랫폼에서 호환된다 -> 범용성
• REST API 메시지가 의도하는 바를 명확하게 나타내므로 의도하는 바를 쉽게 파악할 수 있다.
• 서버와 클라이언트의 역할을 명확하게 분리한다.

REST API의 단점

• 표준이 존재하지 않는다.
• 사용할 수 있는 메소드가 4가지 밖에 없다.
• 구형의 브라우저가 아직 지원하지 못하는 부분이 존재한다.

2-4) 요약정리

웹상에서 사용되는 여러 리소스를 stateless 클라이언트 서버 프로토콜주에서 HTTP URL로 표현하고 그 리소스에 대한 행위를 HTTP method로 정의하는 것

3. GraphQL

3-1) GraphQL 정의

GraphQL 은 Graph Query Language 의 줄임말이다.
Query Language 는 정보를 얻기 위해 보내는 질의문(Query)을 만들기 위해 사용되는 Computer 언어의 일종이다.

GraphQL 은 이런 Query Language 중에서도 Server API 를 통해 정보를 주고받기 위해 사용하는 Query Language 이다.

3-2) GraphQL 탄생배경

REST 방법론이 있는데도 새로운 언어인 GraphQL 이 탄생해야했던 배경은 무엇인가?

RESTful API 로는 다양한 기종에서 필요한 정보들을 일일히 구현하는 것이 힘들었다.

예로 IOS와 Andriod에서 필요한 정보들이 조금씩 달랐고, 그 다른 부분마다 API를 구현하는 것이 힘들었다.
이 때문에 정보를 사용하는 측에서 원하는 대로 정보를 가져올 수 있고, 보다 편하게 정보를 수정할 수 있도록 하는 표준화된 표준화된 Query language 를 만들게 되었다.

3-2) RESTful 과의 차이점

• GraphQL API 는 주로 전체 API를 위해서 하나의 Endpoint 를 사용한다.
  (RESTful API 는 Resource 마다 하나의 Endpoint 를 가지고, 그 Endpoint 에서 그 Resource 에 대한 (거의) 모든 것을 담당한다.)

• GraphQL API 는 요청할 때 사용한 Query 문에 따라 응답의 구조가 달라진다.

• GraphQL API 는 유연하다 백엔드에서 지정해놓는 틀이 거의 없기 때문이다.

3-3) REST 장점과 단점

GraphQL API의 장점
1. HTTP 요청의 횟수를 줄일 수 있다.

• RESTful 은 각 Resource 종류 별로 요청을 해야하고, 따라서 요청 횟수가 필요한 Resource 의 종류에 비례한다.
• 반면 GraphQL 은 원하는 정보를 하나의 Query 에 모두 담아 요청하는 것이 가능하다.

2. HTTP 응답의 Size 를 줄일 수 있다.

• RESTful 은 응답의 형태가 정해져있고, 따라서 필요한 정보만 부분적으로 요청하는 것이 힘들다.
• 반면 GraphQL 은 원하는 대로 정보를 요청하는 것이 가능하다.

GraphQL API의 단점
1. File 전송 등 Text 만으로 하기 힘든 내용들을 처리하기 복잡하다.
2. 고정된 요청과 응답만 필요할 경우에는 Query 로 인해 요청의 크기가 RESTful API 의 경우보다 더 커진다.
3. 재귀적인 Query 가 불가능하다. (결과에 따라 응답의 깊이가 얼마든지 깊어질 수 있는 API 를 만들 수 없다.)

4. GraphQL or RESTful?

그렇다면 어떤 것을 선택해서 사용해야하는가?
다음과 같은 기준으로 선택하면 될 것이다.

GraphQL

• 서로 다른 모양의 다양한 요청들에 대해 응답할 수 있어야 할 때
• 대부분의 요청이 CRUD(Create-Read-Update-Delete) 에 해당할 때

RESTful

• HTTP 와 HTTPs 에 의한 Caching 을 잘 사용하고 싶을 때
• File 전송 등 단순한 Text 로 처리되지 않는 요청들이 있을 때
• 요청의 구조가 정해져 있을 때

둘 중 하나만 선택해야 할 필요는 없다.
하나의 Endpoint를 GraphQL 용으로 만들고, 다른 RESTful Endpoint 들을 만들어 놓는 것은 API 개발자의 자유다.
주의해야할 것은 하나의 목표를 위해 API structure를 섞어놓는 것은 API의 품질을 떨어트릴 수 있다.

(예: 사용자 정보를 등록하는 것은 RESTful API 로, 사용자 정보를 수정하는 것은 GraphQL API 로 한다면 끔찍할 것이다.)

결론

GraphQL 은 여러 장점을 가지고 Server 의 구조를 단순화 시켜줄 수 있는 좋은 Query Language 이다.
다만, GraphQL 의 장점이 언제나 의미를 가지는 것은 아니며, 어떤 조건에서 사용하는지, 어떤 목표로 사용하는지에 따라서 장점으로 작용하기도, 단점으로 작용하기도 한다.
훌륭한 API 개발자가 되기 위해서는 이런 장단점을 잘 파악하여 GraphQL 만 쓸 것인지, RESTful structure 또한 사용할 것인지,혹은 RESTful structure 만 사용할 것인지를 결정하는 것이 중요하다.