GraphQL の追加プロパティ

GraphQL は、規模を問わずシンプルさと堅牢性を維持するためのいくつかの設計原則で構成されています。

宣言型

GraphQL は宣言型です。つまり、ユーザーはクエリしたいフィールドを宣言するだけでデータを記述 (整形) できます。レスポンスはこれらのプロパティのデータのみを返します。例えば、DynamoDB テーブル内のBookオブジェクトを 13 ISBN idの値で取得する オペレーションを次に示します。9780199536061:

{
  getBook(id: "9780199536061") {
    name
    year
    author
  }
}

このレスポンスでは、ペイロード内のフィールド (name、year、author) が返され、それ以外は何も返されません。

{
  "data": {
    "getBook": {
      "name": "Anna Karenina",
      "year": "1878",
      "author": "Leo Tolstoy",
    }
  }
}

この設計原則により、GraphQL は複雑なシステムで REST APIs を処理するオーバーフェッチとアンダーフェッチという、アクルードごとの問題を排除します。その結果、データ収集がより効率的になり、ネットワークパフォーマンスが向上します。

階層的

GraphQL は、要求されたデータをアプリケーションのニーズに合わせてユーザーが形作ることができるという点で柔軟です。リクエストされたデータは、常に GraphQL で定義されているプロパティのタイプと構文に従いますAPI。例えば、次のスニペットは、 にリンクされたすべての保存された引用文字列とページを返quotesす という新しいフィールドスコープを持つ getBookオペレーションを示しています。 Book9780199536061:

{
  getBook(id: "9780199536061") {
    name
    year
    author
    quotes {
      description
      page
    }
  }
}

このクエリを実行すると次の結果を返します。

{
  "data": {
    "getBook": {
      "name": "Anna Karenina",
      "year": "1878",
      "author": "Leo Tolstoy",
      "quotes": [
         {
            "description": "The highest Petersburg society is essentially one: in it everyone knows everyone else, everyone even visits everyone else.",
            "page": 135
         },
         { 
            "description": "Happy families are all alike; every unhappy family is unhappy in its own way.",
            "page": 1
         },
         {        
            "description": "To Konstantin, the peasant was simply the chief partner in their common labor.",
            "page": 251
         }
      ]
    }
  }
}

ご覧のように、リクエストされた本にリンクされている quotes フィールドは、クエリで記述されたのと同じ形式の配列として返されました。ここでは示していませんが、GraphQL には、取得するデータの場所にこだわらないという利点もあります。Books と quotes は別々に保存することもできますが、アソシエーションが存在する限り、GraphQL は引き続き情報を取得します。つまり、クエリは 1 回のリクエストで多数のスタンドアロンデータを取得できるということです。

イントロスペクティブ

GraphQL は自己文書化されている、つまりイントロスペクティブです。スキーマ内の基になる型やフィールドをユーザーが確認できるようにするいくつかの組み込み操作をサポートしています。例えば、Foo およびdate フィールドのある description 型があります。

type Foo {
	date: String
	description: String
}

_type オペレーションを使うと、スキーマの下にあるタイピングメタデータを検索できます。

{
  __type(name: "Foo") {
    name                   # returns the name of the type
    fields {               # returns all fields in the type
      name                 # returns the name of each field
      type {               # returns all types for each field
        name               # returns the scalar type
      }
    }
  }
}

これは応答を返します。

{
  "__type": {
    "name": "Foo",                     # The type name
    "fields": [
      {
        "name": "date",                # The date field
        "type": { "name": "String" }   # The date's type
      },
      {
        "name": "description",         # The description field
        "type": { "name": "String" }   # The description's type
      },
    ]
  }
}

この機能は、特定の GraphQL スキーマがどのタイプとフィールドをサポートしているかを調べるために使用できます。GraphQL は、さまざまなイントロスペクティブなオペレーションをサポートしています。詳細については、「イントロスペクション」を参照してください。

強力なタイピング

GraphQL は、型と項目のシステムを通じて厳密な型指定をサポートしています。スキーマで何かを定義する場合は、実行前に検証できる型でなければなりません。また、GraphQL の構文仕様に従わなければなりません。この概念は他の言語のプログラミングと何ら変わりはありません。例えば、先ほどの、Foo 型があります。

type Foo {
	date: String
	description: String
}

Foo が作成されるオブジェクトであることがわかります。Foo のインスタンス内には、date および description フィールドがあり、両方とも Stringプリミティブ型 (スカラー) です。構文的には、Foo が宣言されていて、そのフィールドがスコープ内に存在していることがわかります。この型チェックと論理構文の組み合わせにより、GraphQL APIが簡潔で明確になります。GraphQL のタイピングと構文の仕様については、こちらを参照してください。