GraphQL In Action | GraphQL API

GraphQL API

그래프QL서버에 데이터를 요청할 때는 그래프QL 쿼리 언어로 작성된 요청을 보낸다. 그리고 이 요청에는 트리형 필드가 포함된다.

그래프QL 커뮤니케이션의 핵심은 요청 객체이다. 그래프QL 요청은 문서(Document)라고도 불린다. 문서는 쿼리, 변경, 구독과 같은 작업 요청을 텍스트로 가지고 있다.
또한, 이런 주요 작업 외에도 기타 작업을 구성할 때 사용하는 조각도 텍스트로 저장된다.

요청

그래프QL 요청에는 변수의 값을 나타내는 객체도 포함되며, 처리와 관련 메타 정보도 포함될 수 있다. 요청 문서에 작업이 하나만 포함돼 있다면 서버는 해당 작업을 알아서 실행한다.
이 경우 작업에 이름을 붙일 필요가 없지만, 일반적으로는 모든 작업에 이름을 붙이는 편이 좋다.

만약 내가 3가지 요청을 한번에 다 보냈다고 하자.

query GetEmployees($active: Boolean!) {
  allEmployess(active: $active) {
    ...employeeInfo
  }
}

query FindEmployee {
  employee(id: $employeeId) {
    ...employeeInfo
  }
}

fragment employeeInfo on Employee {
  name
  email
  startDate
}

이 문서는 일반 변수를 사용하고 있어서 요청에 대한 구체적인 값을 표현하기 위해 JSON객체가 필요하다.

{
  "active": true,
  "employeeId": 42
}

또한 문서가 하나 이상의 작업(GetEmployee와 FindEmployer)을 가지고 있으므로, 어떤 작업을 실행할지를 지정해야한다.

operationName= "GetEmployees"

세가지 요청 요소를 모두 그래프QL 서버로 보내면 서버는 문서 전체를 읽어들인뒤 해석해서 GetEmployee 쿼리를 선택하고 변수를 그에 맞는 값으로 채운다. 그리고 해당 쿼리에 대한 데이터를 반환한다.

그래프QL에선 세가지 종류의 작업을 사용할 수 있다.

• query: 읽기 전용으로 데이터를 추출한다.
• mutation: 데이터를 변경 후 추출한다.
• subscription: 실시간으로 데이터 변경 내용을 받는다.

구독 작업은 서버상의 정보가 변경될 때마다 그래프QL서버가 소켓을 열어서 클라이언트 연결을 허용한다. 이 기능은 UI 뷰가 최신 상태를 유지하도록 지속저긍로 데이터를 폴링(polling)하는 것보다 훨씬 효율적이다.

필드

그래프QL 작업에서 핵심이 되는 요소 중 하나가 필드이다.
그래프QL의 작업을 아주 간단하게 설명하면 객체의 필드를 선택하는 일이라고 할 수 있다.

필드는 추출해야할 객체의 개별 정보 단위를 기술한 것이다.

스칼라 타입은 기본 리프(leaf) 값을 나타내며 그래프QL 스키마에선 스칼라 타입인 Int, String, Float, Boolean을 지원한다.

기본 내장된 ID 스칼라 값은 고유성을 표현하는데 사용된다.

그래프QL 스키마를 변경해서 지정한 형식의 스칼라값을 사용할 수도 있다. 예를 들어 스칼라값 Time을 사용해서 시간을 표준 형식(ISO/UTC)으로 표현하도록 스키마를 설계할 수도 있다.

모든 그래프QL 작업은 선택 세트를 필드에 기술해서 스칼라값(리프값)을 반환해야한다. 즉, 선택 세트가 없는 객체를 필드로 작성할 수 없다. 해당 객체가 어떤 스칼라값을 추출해야하는지를 알 수 없기 때문이다.

루트 필드는 보통 애플리케이션과 현재 사용자가 어디서든 접근할 수 있는 정보를 기술한다.
루트 필드의 전형적인 예로 현재 로그인한 사용자정보가 있다. 이 필드는 viewer나 me같은 이름을 사용한다.

{
  me {
    username
    fullName
  }
}

그래프QL에서는 한줄 주석을 하기 위해 #을 사용한다. 그래프QL에서 여러줄 주석을 지정하는 기능이 없지만, 각줄마다 #을 붙여서 원하는 줄을 주석처리할 수 있다. 서버는 주석을 모두 지나치고, 공백이나 줄바꿈 문자, 그리고 필드 사이의 불필요한 쉼표등을 무시한다. 이런 문자들은 그래프QL 처리에 영향을 주지 않으므로 코드 텍스트의 가독성을 향상시키기 위해 사용할 수 있다.

https://docs.github.com/en/graphql/overview/explorer (깃헙 예제 실습)

Introspective Query

그래프QL API는 내향성 쿼리를 제공해서 API 스키마에 대한 정보를 공개한다.
내향성은 그래프QL 툴에 강력한 기능성을 제공해서 그래피컬 편집기의 바탕이되기도 한다.
그래피컬의 자동완성 목록은 이 내향성 쿼리를 기반으로 한다.

내향성 쿼리는 *type 또는 *schema라는 루트 필드로 시작하는데, 이런 필드들을 메타필드라고 한다.

__typename이라는 메타 필드도 있는데 객체 타입의 이름을 추출할 때 사용한다. 필드명이 두개의 밑줄로 시작하는 것은 내향성용으로 지정된 예약어이다.

메타필드는 암묵적 필드로 필드목록에 표시되지는 않는다.

__schema 필드는 타입이나 지시문 등 API 스키마 정보를 확인할 때 사용한다.
깃허브 API 스키마가 어떤 타입을 지원하는지 물어보자.
다음은 이를 위한 내향성 쿼리이다.

{
  __schema {
    types {
      name
      description
    }
  }
}

이 쿼리는 해당 스키마가 지원하는 모든 타입을 반환하며 각 타입별 설명도 포함한다. 이 타입 목록은 깃허브 graphql 스키마에 정의도니 타입을 확인할 때 유용하다. 예를 들면 깃허브 API 스키마가 Repository, Commit, Issue, PullRequest는 물론이고 이외에도 다양한 타입을 지원한다는 것을 알 수 있다.

단일 타입에 대한 정보가 필요하다면 __type 메타 필드를 사용하면 도니다. 다음 쿼리는 Commit 타입을 지원하는 모든 필드를 인수와 함께 반환한다.

{
  __type(name: "Commit") {
    fields {
      name
      args {
        name
      }
    }
  }
}

정리

• 그래피컬은 브라우저 기반 IDE로 그래프QL 요청을 작성하고 테스트할 수 있다. 그래프QL 쿼리를 작성하고 검증 및 검사할 수 있는 다양한 기능을 제공한다. 이 기능들은 그래프 QL의 내향성에 기반하며 필수 스키마에 포함된다.
• 그래프QL 요청은 작업과 변수용 객체, 메타 정보요소로 구성된다.
• 그래프QL 작업은 트리형 필드를 사용한다. 필드는 정보의 단위이며 그래프QL 언어의 주요 역할은 객체상의 필드를 선택하는 것이다.
• 깃허브는 강력한 그래프QL API를 제공한다. 레포지터리와 사용자 관련 정보를 불러올 수 있고, 레포에 별점을 부여하거나 이슈에 댓글을 다는 등의 변경 작업도 할 수 있다.
• 그래프QL 내향성 쿼리는 클라이언트가 그래프QL API의 메타 정보를 읽을 수 있게 해준다.