GraphQL 소개

GraphQL 용어

GitHub GraphQL API는 GitHub REST API의 아키텍처 변화 및 개념적 변화를 나타냅니다. GraphQL API 참조 문서에서 몇 가지 새로운 용어가 눈에 띌 수 있습니다.

스키마는 GraphQL API의 형식 시스템을 정의합니다. 스키마는 클라이언트가 액세스할 수 있는 가능한 데이터(개체, 필드, 관계, 모든 것)의 전체 집합을 설명합니다. 클라이언트의 호출은 스키마에 대해 유효성이 검사되고 실행됩니다. 클라이언트는 내적 검사를 통해 스키마에 대한 정보를 찾을 수 있습니다. 스키마는 GraphQL API 서버에 상주합니다. 자세한 내용은 “GraphQL API 검색”을 참조하세요.

필드

필드는 개체로부터 검색할 수 있는 데이터 단위입니다. 공식 GraphQL 문서에 따르면 “GraphQL 쿼리 언어는 기본적으로 개체의 필드를 선택하는 것입니다.”

공식 사양은 필드에 대해서도 언급합니다.

모든 GraphQL 작업은 명확한 형태의 응답을 보장하기 위해 스칼라 값을 반환하는 필드까지 선택 항목을 지정해야 합니다.

즉, 스칼라가 아닌 필드를 반환하려고 하면 스키마 유효성 검사에서 오류가 발생합니다. 모든 필드가 스칼라를 반환할 때까지 중첩된 하위 필드를 추가해야 합니다.

인수

인수는 특정 필드에 연결된 키-값 쌍의 집합입니다. 일부 필드에는 인수가 필요합니다. 변형에는 인수로서 입력 개체가 필요합니다.

구현

GraphQL 스키마는 _implements_라는 용어를 사용하여 개체가 인터페이스에서 상속되는 방식을 정의할 수 있습니다.

인터페이스 X와 개체 Y를 정의하는 스키마의 인위적인 예제는 다음과 같습니다.

interface X {
  some_field: String!
  other_field: String!
}

type Y implements X {
  some_field: String!
  other_field: String!
  new_field: String!
}

즉, 개체 Y에는 인터페이스 X와 동일한 필드/인수/반환 형식이 필요하지만, 개체 Y에 특정한 새 필드가 추가됩니다. !는 필드가 필요하다는 의미입니다.

참조 문서에서 다음을 찾을 수 있습니다.

각 개체는 Implements 아래에 자신이 상속되는 인터페이스를 나열합니다.__
각 인터페이스는 Implementations 아래에 자신으로부터 상속되는 개체를 나열합니다.__

query {
  __schema {
    types {
      name
      kind
      description
      fields {
        name
      }
    }
  }
}

특정 형식에 대한 세부 정보를 가져오려면 __type을 쿼리합니다.

query {
  __type(name: "Repository") {
    name
    kind
    description
    fields {
      name
    }
  }
}

GET 요청을 통해 스키마의 _내적 검사 쿼리_를 실행할 수도 있습니다.
```
curl -H "Authorization: bearer TOKEN" http(s)://HOSTNAME/api/graphql
```
참고: "message": "Bad credentials" 또는 401 Unauthorized 응답을 받는 경우 유효한 토큰을 사용하고 있는지 확인하세요. Resource not accessible by personal access token 내용의 403 오류가 발생하는 경우 fine-grained personal access token이(가) 올바른 리소스 소유자를 대상으로 하는지 확인합니다. 예를 들어 액세스하려는 리포지토리를 소유하는 조직을 대상으로 해야 합니다.

결과는 JSON이므로 쉽게 읽고 검색할 수 있도록 출력하는 것이 좋습니다. jq와 같은 명령줄 도구를 사용하거나 이 목적을 위해 결과를 python -m json.tool에 파이프할 수 있습니다.

또는 idl 미디어 형식을 전달하여 스키마의 압축된 버전인 IDL 형식으로 결과를 반환할 수 있습니다.
```
$ curl -H "Authorization: bearer TOKEN" -H "Accept: application/vnd.github.v4.idl" \
http(s)://HOSTNAME/api/graphql
```
참고: 내적 검사 쿼리는 아마도 GraphQL에서 실행할 유일한 GET 요청일 것입니다. 본문을 전달하는 경우 GraphQL 요청 메서드는 쿼리든 변형이든 상관없이 POST입니다.

끌어오기 요청에 관한 자세한 내용은 “GraphQL을 사용하여 통화 구성”을 참조하세요.

이 문서의 내용

GraphQL 용어

스키마

필드

인수

구현

연결

Edge

노드

GraphQL API 검색