소프트웨어 인디오게임 다야 | 매그넘홀덤 개발자 대부분은 웹 API라고 하면 REST(REpresentational State Transfer)를 떠올린다. REST에서는 요청별 URL로 요청을 보내고, 애플리케이션에 맞는 형식으로 결과를 받는다.

메타의 웹 API 시스템인 그래프QL(GraphQL)은 다른 종류의 API다. 그래프QL에서 개발자는 요청과 응답 모두를 엄격한 유형의 쿼리 언어로 정의함으로써 애플리케이션이 API로부터 정확히 어떤 데이터를 얻고자 하는지 지정할 수 있다. 그래프QL은 보다 효율적이고 구조적이며, 체계적인 REST 대안으로 평가받는다.

인디오게임 다야 | 매그넘홀덤 여기서는 그래프QL과 REST의 차이점, 이 차이점이 API 설계에 미치는 영향, 그리고 서버에서 데이터를 불러오는 용도로 많은 경우 그래프QL이 REST보다 더 나은 선택인 이유를 알아본다.

그래프QL vs. REST
REST에서는 일반적으로 특별히 만들어진 URL을 통해 요청을 제출하며 각 요청은 서로 다른 엔드포인트로 전송된다(예를 들어 /movie/2120, /director/5130).

그래프QL에서는 JSON과 비슷한 쿼리로 찾는 데이터에 대한 선언적 요청을 제출하며, 모든 요청이 동일한 엔드포인트로 전송된다. 돌려받는 데이터는 요청에 사용되는 스키마에 따라 결정된다. 필요한 특정 데이터만 요청하기 위한 표준화된 자체 설명적 방법이다. 다양한 요청 유형에 대해 서로 다른 엔드포인트 URL 형식이 아니라 서로 다른 스키마를 사용하는 방식으로, 쿼리 메커니즘이 훨씬 더 유연해진다.

인디오게임 다야 | 매그넘홀덤 많은 REST API 역시 공통 사양인 스웨거(Swagger)를 준수하지만, REST API가 스웨거에 의해 생성돼야 한다는 규칙은 없다. 그래프QL은 기본적으로 API에 대한 공식 정의를 제공한다. 이런 측면에서 그래프QL은 SQL과 비슷한 면이 있다. SQL 기반 데이터 소스에서는 모든 데이터 요청에 대해 하나의 공통 엔드포인트에 연결하며, 요청의 형식에 따라 돌려받는 레코드가 결정된다. 또한 SQL에는 많은 구현이 있지만 SQL 쿼리 구문은 이런 구현 전반에서 상당히 일관적이다.

그래프QL 쿼리
앞서 언급했듯이 그래프QL은 불러올 데이터가 쿼리와 응답에서 어떻게 구성되는지를 스키마 또는 데이터 정의를 사용해서 설명한다. 객체 관계 매퍼(object-relational mapper, ORM)을 다뤄본 사람이라면 누구나 그래프QL의 데이터 스키마 정의가 익숙하게 느껴질 것이다. 다음 예제를 보자.

type Movie {
id: ID
title: String
released: Date
director: Director
}

type Director {
id: ID
name: String
movies: [Movie]
}

스키마의 각 요소에는 유형 정의가 있다. 그래프QL에는 쿼리를 위한 자체 유형 시스템이 있으며, 이 시스템은 수신되는 스키마의 유효성을 검사하고 정의와 일치하는 형식으로 데이터를 반환하는 데 사용된다.

그래프QL에 제출되는 쿼리는 스키마에 의해 비슷하게 정의된다.

type Query {
movie_title(title: String!): Movie
director(id: ID): Director
}

이 쿼리는 최대 2개의 매개변수 movie_title, director를 받는다(각각 title과 ID를 통해 받음).

유형 옆의 !는 쿼리의 필수 요소임을 나타낸다. 즉, title로 영화를 쿼리해야 하며 director는 선택 사항(쿼리 범위를 좁히는 용도)이다.

필수 요소는 데이터 스키마에서도 사용될 수 있다. 다음과 같이 ID만으로 영화를 검색하는 쿼리도 가능하다.

query GetMovieByID ($id: ID!) {
movie(id: $id) {
name
}
}

이 쿼리는 따로 정의된 변수($id)를 사용해서 ID 번호로 영화를 조회해서 이름을 반환한다. 그래프QL 쿼리는 개별 필드뿐만 아니라, 필드 안에 항목이 배열을 중첩하는 방식으로 관련 객체와 해당 필드도 반환할 수 있다.

쿼리를 위한 변수는 다음과 같은 형식을 사용해 쿼리의 별도 섹션에서 전달된다.

{
“id”: 23
}

그래프QL 유형
그래프QL의 쿼리 유형 시스템은 문자열, 정수와 같은 많은 일반적인 스칼라 유형을 지정한다. 대부분의 쿼리는 이런 유형을 중심으로 구성된다. 그러나 유형 시스템에는 더 정교한 쿼리를 위한 다음과 같은 여러 가지 고급 유형도 포함된다.

interface 유형은 다른 유형에서 구현 및 재사용할 수 있는 사전 정의된 필드 집합이 있는 추상 유형을 만드는 데 사용할 수 있다.
union 유형은 한 종류의 쿼리에서 여러 유형에 걸쳐 다양한 종류의 결과를 반환할 수 있게 해준다.
input 유형은 위와 같은 종류의 객체 전체를 매개변수로 전달하는 데 사용할 수 있다(이러한 객체가 유효성 검사가 가능한 일반적인 스칼라 유형에서 생성된 경우).

인터페이스 또는 유니언 객체를 다루는 경우 인라인 조각 및 지시문을 사용해서 해당 객체 유형이 지정할 수 있는 조건을 기반으로 데이터를 반환해야 한다.

쿼리에서 반환 가능한 또 다른 유형은 선택적인 edges 필드에 반환되는 edge 유형이다. 에지에는 nodes(데이터 레코드), 그리고 해당 객체에서의 앞뒤 페이지 매김 방법에 대한 컨텍스트 정보를 제공하는 인코딩된 문자열인 cursors가 포함된다.

{
movie {
name
actors (first:5) {
edges {
cursor
node {
name
}
}
}
}
}

이 예제에서 movie 노드는 영화와 배우의 이름을 반환한다. 영화의 각 배우에 대해 배우 이름이 포함된 노드와 배우의 “이웃”을 탐색할 수 있게 해주는 커서를 받게 된다.

그래프QL을 사용한 페이지 매김
데이터 소스를 다룰 때 일반적인 시나리오는 커서를 통해 페이지 단위로 데이터를 요청하는 것이다. 그래프QL은 여러 가지 페이지 매김 방법을 제공한다.

레코드를 요청할 때 요청할 레코드의 수와 시작 오프셋뿐 아니라 연속된 페이지를 요청하는 방법도 지정할 수 있다. 위 섹션의 예제 코드는 괄호 안의 first:5 매개변수에 지정된 대로 특정 영화와 관련된 처음 5명의 배우만 반환한다.

actors 뒤의 first: 절 뒤에 이어지는 항목을 불러올 방법을 설명하는 다른 키워드를 붙일 수 있다. offset:은 간단한 오프셋에 사용할 수 있지만 오프셋은 데이터가 추가 또는 삭제될 때 폐기될 수 있다.

가장 견고한 페이지 매김을 위해서는 위에서 설명한 edge 유형을 사용해서 현재 요청 중인 객체와 함께 제공할 수 있는 커서를 사용하는 것이 좋다. 이렇게 하면 페이지 매김 사이에 데이터가 삽입 또는 삭제될 때(예를 들어 객체의 고유 ID 또는 고유한 다른 속성을 다른 계산의 시작 키 인덱스로 사용하는 경우) 끊기지 않는 페이지 매김 메커니즘을 만들 수 있다.

그래프QL 뮤테이션을 사용한 데이터 변경
REST API에서는 POST, PATCH 및 기타 HTTP 동사를 사용하는 요청을 제출해서 서버 측 데이터를 변경한다. 그래프QL에서는 변경을 위한 특정 쿼리 스키마인 뮤테이션 쿼리를 사용한다. 이 부분도 SQL이 UPDATE 또는 DELETE 쿼리를 사용하는 것과 거의 같은 방식이다.

데이터를 변경하려면 뮤테이션 스키마라는 스키마를 사용해서 그래프QL 쿼리를 제출한다.

mutation CreateMovie ($title: String!, $released: Date!) {
createMovie (title: $title, released: $released){
id
title
released
}
}

[submitted data]

{
“title”: “Seven Samurai”
“released”: “1950”
}

뮤테이션 쿼리를 포함한 모든 쿼리는 데이터를 반환할 수 있다. 여기서 createMovie 뒤의 중괄호 안에 있는 필드 목록은 이 요청으로 새 레코드가 생성된 후 서버에서 무엇을 반환해야 하는지를 지정한다. 여기서 id 필드의 값은 데이터베이스에 의해 생성되고 다른 필드의 값은 쿼리에서 제출된다.

또 한가지 유의해야 할 점은 데이터를 반환하는 데 사용되는 쿼리와 데이터 유형은 데이터를 요청하는 데 사용된 것과 설계상 다르다는 것이다. 뮤테이션 쿼리는 수신되는 데이터를 검증해야 하며 따라서 이러한 쿼리에 사용되는 유형은 이 기능을 위한 유형이다. 마찬가지로, 반환된 쿼리 객체에 사용되는 필드는 검증이 아닌 표시용이다. 쿼리에서 반환되는 그래프QL 객체에는 순환 참조 또는 기타 문제가 있는 필드가 포함될 수 있고 이 경우 쿼리 매개변수로 사용할 수 없게 된다.

왜 그래프QL인가?
REST가 아닌 그래프QL을 선택하는 주된 이유는 그래프QL 쿼리의 명시적, 선언적 특성에 있다. 쿼리와 반환되는 데이터의 형태에 대한 공식적인 정의가 있으면 여러 API와 구현에 걸친 일관성 외에도 다른 여러 이점을 얻을 수 있다.

API 에반젤리스트 필 스터전이 그래프QL과 REST를 비교한 글에서 언급했듯이, 그래프QL의 필드 구조는 전체 API를 버저닝하는 방식과 달리 시간 경과에 따라 특정 필드를 폐기하거나 가져올 수 있으므로 쿼리에 더 세분화된 버저닝을 더 쉽게 적용할 수 있다. 그래프QL에서도 여전히 일괄적인 버저닝 접근 방식을 사용할 수 있다. 핵심은 변경 사항을 적용할 때 반드시 그렇게 할 필요는 없다는 것이다.

그래프QL API를 위한 오픈소스 툴 개발업체인 아폴로 그래프QL(Apollo GraphQL)의 엔지니어링 관리자 샤코 스투바일로는 그래프QL 접근 방식의 또 다른 장점인 자체 문서화를 강조한다. 스투바일로는 “가능한 모든 쿼리, 객체, 필드에는 서버에서 표준 방식으로 쿼리할 수 있는 이름, 설명, 유형 정보가 함께 제공된다”라고 말했다.

그래프QL의 자체 문서화는 일종의 성찰 기능도 제공한다. 즉, 쿼리를 사용하여 쿼리 자체에 대한 정보를 반환할 수 있다. 따라서 그래프QL 쿼리를 사용하는 소프트웨어는 특정 필드 집합을 다루기 위해 하드 와이어링을 할 필요 없이 자동으로 필드를 추론할 수 있다.

그래프QL이 더 나중에 나온 기술이고 REST/스웨거가 더 오래되었다는 것만으로 그래프QL을 선호하는 것은 바람직하지 않다. 일상적인 API 설계(The Design of Everyday API)의 저자 아르노 로레는 “그래프QL API도 REST API와 마찬가지로 명확한 목적에 따라 만들어져야 하며, 내부적 관점이 아닌 외부적 관점에서 설계되어야 한다”라고 말했다.
editor@itworld.co.kr

원문보기:
https://www.itworld.co.kr/topnews/345601#csidxff01bd9bc063b96808b1b0efd8a4bb2