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クエリはインタラクティブであり、リレーショナルクエリをネイティブにサポートしています。これは重要な2つのことを意味します：

クエリはいつでも変更できます。
複雑なデータベースクエリやシリアライザを記述することなく、関連データを結合できます。

引数の理解

Archie Core GraphQL APIの力は、クエリを実行するときにさまざまな引数を指定できる機能によってさらに強化されます。これは上記の例で実証されており、特定のUUID文字列がクエリへの引数として渡されています（...citiesById(id: "e14638cb...")）。

データビルダーでデータテーブルを作成する場合、一意としてマークされたフィールドは、クエリの引数として使用できます。

たとえば、CitiesテーブルのIDフィールドが一意に設定されているため（主キーであるため）、特定のCityレコードをクエリできます：

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

変数

APIエクスプローラーで変数を使用することで、クエリを再利用可能かつ動的にすることができます。

変数を操作するには、次のことを行う必要があります：

クエリ内の静的な値を$variableNameに置き換えます。
$variableNameをクエリが受け入れる変数の1つとして宣言します。
別の変数辞書で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"
    }
  }
}

フラグメント

クエリは長く複雑になる可能性があります。フラグメントを作成すると、定義されたセットを表すために使用できるフィールドのセットを作成できます。2人の異なる著者からいくつかのフィールドを取得したい場合、フィールドを2回繰り返す代わりにフラグメントを使用できます。このクエリには、{ ...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"
      }
    },