GraphQL은 페이스북에서 만들었다

Server API

Server API (혹은 Server-side web API)는 적절한 요청을 하였을 때, 그에 맞는 응답을 되돌려주는 창구 (Endpoint)를 Web을 통해 노출한 것을 말한다

이런 Server API 는 어떤 정보들(환율, 주식 시세, 뉴스 등등)을 요청하고 수정하기 위해서 만들어지는 경우가 많다

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

REST 와 RESTful

모든 Resource (자료, User, 정보 등등)들을 하나의 Endpoint 에 연결해놓고, 각 Endpoint는 그 Resource 와 관련된 내용만 관리하게 하자는 방법론이다

예시로 어떤 API 가 Community site 용 API 이며, 이 API 를 사용해 사용자들이 글을 작성/수정/삭제 할 수 있고, 각 글에 댓글을 작성/수정/삭제할 수 있다고 해보자

이때, API 의 Endpoint 를 다음과 같이 구성하면 REST 의 조건을 간략히는 만족하게 된다

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

(물론 실제 API에는 이보다 더 많은 것들 (글 가져오기, 회원가입하기, 회원인증하기, 회원정보 확인하기 등등) 이 필요할 것이다)

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

GraphQl

GraphQL은 Graph Query Language의 줄임말이다

Query Language 란 ?

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

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

GraphQL은 왜 탄생해야했는가?

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

이 때문에 정보를 사용하는 측에서 원하는 대로 정보를 가져올 수 있고, 보다 편하게 정보를 수정할 수 있도록 하는 표준화된 Query language 를 만들게 되었다
이것이 GraphQL이다

GraphQL 과 RESTful 의 차이점

GraphQL 을 통한 API는 RESTful API와는 다른 측면을 보인다

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

API 의 Endpoint

위에서 말했듯 RESTful API는 Resource 마다 하나의 Endpoint를 가지고, 그 Endpoint에서 그 Resource에 대한 (거의) 모든 것을 담당한다

반면, GraphQL은 전체 API를 위해서 단 하나의 Endpoint만을 사용한다

• Github API v3
• Github API v4

각각 v3 root endpoint와 v4 root endpoint로 Endpoint를 제공하지만,
v4의 경우 Root endpoint를 제외한 어떤 Endpoint도 없는 반면, v3의 경우는 각 Resource 마다 수많은 Endpoint들을 제공한다

API 응답의 구조

RESTful API는 하나의 Endpoint에서 돌려줄 수 있는 응답의 구조가 정해져 있는 경우가 많다
API를 작성할 때 이미 정해놓은 구조로만 응답이 오게 되는 것이다
반면, GraphQL은 사용자가 응답의 구조를 자신이 원하는 방식으로 바꿀 수 있다

마찬가지로 Github API 를 예시로 보면,
v3 repository api는 구조가 예시에 나온 모양으로 고정되어 있는 반면,
v4 api 의 경우는

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

를 사용하느냐

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

를 사용하느냐에 따라서 응답의 구조가 완전히 다르게 된다

GraphQL의 장단점

GraphQL 장점

1. HTTP 요청의 횟수를 줄일 수 있다

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

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

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

GraphQL 단점

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

GraphQL or RESTful

GraphQL

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

RESTful

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

GraphQL and RESTful

File 전송과 같이 RESTful이 더 유리한 API 가 있을 수 있고, 다양한 정보를 주고받는 것 같이 GraphQL이 더 유리한 API가 있을 수 있다

이럴 때 둘 중 하나만 선택해야할 필요는 없다
하나의 Endpoint를 GraphQL 용으로 만들고, 다른 RESTful endpoint 들을 만들어 놓는 것은 API 개발자의 자유다

주의해야할 것은 하나의 목표를 위해 두 API structure를 섞어놓는 것은 API의 품질을 떨어트릴 수 있다는 점이다
(ex, 사용자 정보를 등록하는 것은 RESTful API 로, 사용자 정보를 수정하는 것은 GraphQL API 로 한다면...)

즉, 유리한 쪽으로 잘 선택해서 적정하게 사용하면 꽤 괜찮은 API를 만들 수 있을꺼 같다