RESTful API 와 GraphQL 차이

Server API

: 서버 API 란 적절한 요청을 하였을 때, 그에 맞는 응답을 되돌려주는 창구(Endpoint)를 Web을 통해 노출한 것을 말한다.

정보를 요청하고 수정하기 위해서 만들어지는 경우가 많다.

이 서버 API 를 만드는 방법론 중에는 REST 와 GraphQL 이 있다.

REST 와 RESTful

: REST 는 Resource 들을 하나의 Endpoint에 연결해놓고, 각 Endpoint 는 그 Resource와 관련된 내용만 관리하게 하자는 방법론이다.

예를 들어 사용자들이 글을 작성, 수정, 삭제 할 수 있고, 각 글에 댓글을 작성, 수정, 삭제 할 수 있다고 해보면

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

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

GraphQL

GraphQL 은 Graph Query Language 의 줄임말이다.

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

Facebook 에서 만든 Query Language 인데, Facebook 에서 Graph QL 을 만든 이유에 대해 다음과 같이 밝혔다.

Restful API 로는 다양한 기종에서 필요한 정보들을 일일히 구현하는 것이 힘들었다. 예를 들어 IOS 와 Android 에서 필요한 정보들이 조금씩 달랐고, 그 다른 부분마다 API를 구현하는 것이 힘들었다.

GraphQL API 는 주로 하나의 Endpoint 를 사용하고, 요청할 때 사용한 Query 문에 따라 응답의 구조가 달라진다.

GraphQL 과 RESTful의 차이점

1. RESTful API 는 Resource 마다 하나의 Endpoint 를 가지고, 그 Endpoint 에서 그 Resource 에 대한 거의 모든 것을 담당한다. 반면, GraphQL 은 전체 API 를 위해서 단 하나의 Endpoint 만을 사용한다.

2. Restful API 는 하나의 Endpoint 에서 돌려줄 수 있는 응답의 구조가 정해져 있는 경우가 많다. 반면, GraphQL 은 사용자가 응답의 구조를 자신이 원하는 방식으로 바꿀 수 있다.

예를 들어, 

query { 
  repository(owner: "Ailrun" name: "rxan") {
    nameWithOwner
  }
}

를 사용하느냐,

query { 
  repository(owner: "Ailrun" name: "rxan") {
    languages(first: 2) {
      nodes {
        name
      }
    }
  }
}

를 사용하느냐에 따라 응답의 구조가 다르게 된다.

GraphQL 의 장점

1. HTTP 요청의 횟수를 줄일 수 있다.
   • RESTful 은 각 Resource 종류 별로 요청을 해야하고, 따라서 요청 횟수가 필요한 Resource 의 종류에 비례한다.
     반면 GraphQL 은 원하는 정보를 하나의 Query 에 모두 담아 요청하는 것이 가능하다.
2. HTTP 응답의 Size 를 줄일 수 있다.
   • RESTful 은 응답의 형태가 정해져있고, 따라서 필요한 정보만 부분적으로 요청하는 것이 힘들다.
     반면 GraphQL 은 원하는 대로 정보를 요청하는 것이 가능하다.

예를 들어 글의 목록(5개)과 글에 쓰인 댓글의 목록을 가져올 수 있는 API 가 있다고 해보면

Restful 하게 작성되었다면 아래 세가지의 경우 중 하나의 선택해야 한다.

1. 글의 목록을 가져오는 Endpoint 에 요청을 하고,
   각 글마다 댓글의 목록을 가져오는 Endpoint 에 요청을 5 번 해야 글과 댓글의 목록을 모두 가져올 수 있을 것이다.
2. 글의 목록을 가져오는 Endpoint 의 응답에 댓글의 목록을 포함한다.
   이 경우에는 글의 목록을 가져오는 Endpoint 에 요청을 1 번 하면 끝이지만,
   글의 목록만 가져와야 하는 경우나 몇몇 글의 댓글만 가져와야 하는 경우가 있다면
   필요한 정보에 비해서 응답의 크기가 쓸데없이 큰 경우가 발생할 것이다.
3. 글의 목록을 가져오는 요청에 조건을 달아서 댓글의 목록을 포함할 수도, 포함하지 않을 수도 있게 한다.
   API 에 Endpoint 가 많을 경우, API 를 만드는 것이 점점 더 복잡해지고,
   결국 Facebook 에서 GraphQL 을 만든 이유와 비슷한 상황에 처하게 된다.

반면 같은 API 를 GraphQL 로 작성하였다면

1. 글의 목록만을 가져와야 할 경우에는 글의 목록만을 가져오는 Query 를 작성하여 서버에 요청을 보낸다.
2. 글의 목록과 댓글을 모두 가져와야 할 경우에는 글의 목록과 댓글을 모두 가져오는 Query 를 작성하여 서버에 요청을 보낸다.

등을 할 수 있다.

GraphQL 의 단점

1. File 전송 등 Text 만으로 하기 힘든 내용들을 처리하기 복잡하다.
2. 고정된 요청과 응답만 필요할 경우에는 Query 로 인해 요청의 크기가 RESTful API 의 경우보다 더 커진다

GraphQL or RESTful ?

1. GraphQL
   • 서로 다른 모양의 다양한 요청들에 대해 응답할 수 있어야 할 때
   • 대부분의 요청이 CRUD(Create-Read-Update-Delete) 에 해당할 때
2. RESTful
   • HTTP 와 HTTPs 에 의한 Caching 을 잘 사용하고 싶을 때
   • File 전송 등 단순한 Text 로 처리되지 않는 요청들이 있을 때
   • 요청의 구조가 정해져 있을 때

하지만 둘 중 하나를 선택할 필요는 없다. 하나의 Endpoint 를 GraphQL 용으로 만들고 다른 Restful endpoint 들을 만들어 놓을 수도 있기 때문. 두 방법론의 장단점을 잘 파악하며 결정하는 것이 중요하다!

 

참고

https://www.holaxprogramming.com/2018/01/20/graphql-vs-restful-api/