GraphQL API 개요

Archie Core의 모든 프로젝트는 통합 API 엔드포인트를 사용합니다. 이 단일 엔드포인트는 모든 데이터 테이블에 대한 GraphQL 쿼리, 뮤테이션 및 구독을 처리합니다. API는 필터링, 페이지네이션, 전체 텍스트 검색 및 기타 고급 기능으로 사전 구성됩니다.

모든 API 요청은 다음 URL로 전송됩니다:

https://archie-core.services.archie.com/graphql

요청을 특정 프로젝트로 라우팅하려면 모든 HTTP 요청에 프로젝트 ID가 포함된 x-project-id 헤더를 포함해야 합니다.

alt text

필드 이해하기

GraphQL은 객체의 필드를 요청하기 위한 명세입니다. 다음은 고유한 id로 특정 도시를 찾고 nameCity 및 state 필드를 반환하도록 요청하는 간단한 Archie Core 쿼리입니다.

query MyQuery {
  citiesById(id: "e14638cb-6d72-4a36-b30f-9b763136a7bb") {
    id
    nameCity
    state
  }
}

결과는 다음과 같습니다:

{
  "data": {
    "citiesById": {
      "id": "e14638cb-6d72-4a36-b30f-9b763136a7bb",
      "nameCity": "Chicago",
      "state": "Illinois"
    }
  }
}

결과는 쿼리와 동일한 형태를 가집니다. 이것이 GraphQL의 핵심입니다: 항상 요청한 것을 얻고 서버는 클라이언트가 어떤 필드를 요청하는지 알고 있습니다.

Archie Core GraphQL 쿼리는 대화형이며 관계형 쿼리를 기본적으로 지원합니다. 이는 두 가지 중요한 의미가 있습니다:

쿼리는 언제든지 변경할 수 있습니다.
복잡한 데이터베이스 쿼리와 직렬화기를 작성하지 않고도 관련 데이터를 조인할 수 있습니다.

인수 이해하기

Archie Core GraphQL API의 강력함은 쿼리 실행 시 다양한 인수를 지정할 수 있는 기능으로 더욱 풍부해집니다. 이는 위의 예에서 특정 UUID 문자열이 쿼리에 인수로 전달되는 것으로 입증되었습니다(...citiesById(id: "e14638cb...")).

Data Builder에서 데이터 테이블을 생성할 때 고유로 표시된 모든 필드는 쿼리의 인수로 사용할 수 있습니다.

예를 들어 Cities 테이블에 ID 필드가 고유하게 설정되어 있으므로(기본 키이므로) 특정 City 레코드를 쿼리할 수 있습니다:

query MyQuery {
  citiesById(id: "e14638cb-6d72-4a36-b30f-9b763136a7bb") {
    id
    nameCity
    state
  }
}

변수

API Explorer에서 변수를 사용하여 쿼리를 재사용 가능하고 동적으로 만들 수 있습니다.

변수로 작업하려면 다음이 필요합니다:

쿼리의 정적 값을 $variableName으로 바꿉니다.
$variableName을 쿼리가 허용하는 변수 중 하나로 선언합니다.
별도의 변수 사전에서 variableName: value를 전달합니다.

쿼리는 다음과 같습니다:

query MyQuery ($filter: StudentsFilter) {
  students(filter: $filter) {
    items {
      firstName
      email
    }
  }
}

변수는 다음과 같습니다:

{
  "filter": {
    "isActive": {
      "equals": true
    }
  }
}

결과는 다음과 같습니다:

{
  "data": {
    "students": {
      "items": [
        {
          "firstName": "James",
          "email": "james.smith@example.com"
        },
        {
          "firstName": "John",
          "email": "john.williams@example.com"
        },
        {
          "firstName": "Mary",
          "email": "mary.brown@example.com"
        },
        {
          "firstName": "Mary",
          "email": "mary.johnson@example.com"
        },
        {
          "firstName": "Elizabeth",
          "email": "elizabeth.davis@example.com"
        }
      ]
    }
  }
}

alt text

별칭

별칭은 필드 이름과 다른 이름을 가진 객체를 반환하는 데 사용됩니다. 단일 쿼리에서 다른 인수를 가진 동일한 유형의 객체를 가져올 때 필요합니다.

아래에서 첫 번째 도시의 별칭이 “cityOne”인 것을 볼 수 있습니다:

query MyQuery {
  cityOne: citiesById(id: "e14638cb-6d72-4a36-b30f-9b763136a7bb") {
    id
    nameCity
  }

  cityTwo: citiesById(id: "0174dc55-d494-4ebc-a0e9-13575461cad4") {
    id
    nameCity
  }
}

결과:

{
  "data": {
    "cityOne": {
      "id": "e14638cb-6d72-4a36-b30f-9b763136a7bb",
      "nameCity": "Chicago"
    },
    "cityTwo": {
      "id": "0174dc55-d494-4ebc-a0e9-13575461cad4",
      "nameCity": "Miami"
    }
  }
}

프래그먼트

쿼리는 길고 복잡해질 수 있습니다. 프래그먼트는 정의된 집합을 나타내는 데 사용할 수 있는 필드 집합을 만듭니다. 두 명의 다른 저자로부터 여러 필드를 원하는 경우 필드를 두 번 반복하는 대신 프래그먼트를 사용할 수 있습니다. 이 쿼리에서 { ...studentFrag }라는 프래그먼트가 있습니다:

query MyQuery {
  studentA: studentsById(id: "287cff0a-345b-4cca-9e9a-75a2161238fd") { ...studentFrag}

  studentB: studentsById(id: "97fb89ac-e0ad-44f5-b671-24a1b751287c") { ...studentFrag}
}

fragment studentFrag on Students {
      id
      firstName
      email
      isActive
      city {
        nameCity
        state
      }
    }

결과:

{
  "data": {
    "studentA": {
      "id": "287cff0a-345b-4cca-9e9a-75a2161238fd",
      "firstName": "James",
      "email": "james.smith@example.com",
      "isActive": true,
      "city": {
        "nameCity": "Chicago",
        "state": "Illinois"
      }
    },
    "studentB": {
      "id": "97fb89ac-e0ad-44f5-b671-24a1b751287c",
      "firstName": "John",
      "email": "john.williams@example.com",
      "isActive": true,
      "city": {
        "nameCity": "Seattle",
        "state": "Washington"
      }