GraphQL クライアントのベストプラクティス

Indeed で高品質な API を開発するためのベストプラクティスです。

 

GraphQL クライアントとして、次のベストプラクティスに従ってください。

必要なデータだけをリクエストする

GraphQL では、クライアントは必要なデータだけを正確にリクエストできます。

クライアントが使わないすべてのフィールドや、事前定義したフィールドセットをリクエストしないでください。

GraphQL では、Indeed はフィールドの利用状況を把握できます。クライアントが使わないフィールドをリクエストすると、分析の妨げになり、フィールドを非推奨にするべきかどうかを判断しにくくなります。

GraphQL オペレーションに一意で分かりやすい名前を付ける

GraphQL では、オペレーションに分かりやすい名前を付けられます。分かりやすい名前には Pascal case を使用してください。

自己説明的なオペレーション名は、API の意味とコンテキストをサービス実装者に伝えます。これは、特にスキーマ変更時に有用です。

GraphQL クライアントライブラリでオペレーション名がどのように機能するかを理解してください。適切に使わないと、ライブラリが同じ名前のオペレーションを呼び出すたびに動的な一意名を付けることがあり、可観測性に悪影響を与えます。

推奨

query FetchJobForHomepageModal($id: ID) {
  job(id: $id) {
    result {
      title
    }
  }
}

非推奨

query($id: ID) {
  job(id: $id) {
    result {
      title
    }
  }
}

GraphQL リクエストの引数に変数を使用する

GraphQL クライアントは、variables を使用して、オペレーション内のリテラルに異なる値を代入できます。

変数を使用すると、クライアントが定義したオペレーションを再利用できます。

バックエンドシステムにとっても利点があります。GraphQL サーバーは値の組み合わせごとに解析と検証を行うため、値を直接埋め込むとキャッシュの妨げになるからです。

クライアントはオペレーション定義を再利用できるため、コストの高いオペレーションの再作成を避けられます。また、オペレーション定義を明確で分かりやすい形で表現できます。変数を使用すると、個人を特定できる情報である PII の不適切な取り扱いも避けやすくなります。

推奨

query SurveyAnswers($questionId: QuestionAnswersInput) {
  questionAnswers(input: $questionId) {
    result {
      answerId
      answerText
    }
  }
}

変数

{
  questionId: 124324
}

非推奨

query SurveyAnswers {
  questionsAnswers(input: {
    questionId: 124324
  }) {
    result {
      questionId
      answerId
      answerText
    }
  }
}

一般的なエラーに標準のエラーコードを使用する

API 利用者がエラーを処理しやすいように、最も一般的なエラーには標準のエラーコードを使用してください。

次の一般的なエラーコードを使用します。

JVM ベースの言語では、graphql-exceptions ライブラリがこれらの一般的なエラーコードを ErrorCode enum で提供します。

一般的なエラーコード

エラーコード	説明
BAD_USER_INPUT	入力パラメーターの値が無効です。標準の GraphQL Non-Null チェックと型チェックを超える入力検証には、このエラーコードを使用します。
FORBIDDEN	リクエストには有効な認証資格情報が含まれていますが、クエリまたはミューテーションを許可しません。このエラーコードは、HTTP 403 Forbidden に相当する GraphQL のエラーコードです。FORBIDDEN を使用するときは、列挙攻撃につながる情報を公開しないようにしてください。詳しくは、Testing for User Enumeration and Guessable User Account をご覧ください。
INTERNAL_SERVER_ERROR	サーバーで予期しない障害が発生し、レスポンスを返せません。サーバーで処理できない障害にだけ、この汎用エラーを使用します。
QUERY_TOO_COMPLEX	クエリが 1 回のリクエストで許可される複雑さを超えています。
QUERY_TOO_NESTED	クエリにネストが多すぎます。
UNAUTHENTICATED	リクエストに十分な認証資格情報がないため、サーバーはクエリ、ミューテーション、またはフィールド解決を実行しません。このエラーコードは、HTTP 401 Unauthorized に相当する GraphQL のエラーコードです。

Ruby on Rails クライアント

Ruby on Rails を使用してミューテーションまたはクエリを呼び出すときにオペレーション名を確実に使うには、クエリを定数に保存してください。

たとえば、次のようにミューテーションを呼び出す場合です。

<OperationName>{ variables....} 

オペレーションは、Apollo Studio 上で必ずしも <OperationName> という名前では表示されません。

ライブラリは内部でミューテーションを Ruby 定数に保存します。そうしない場合は、次のような名前を動的に割り当てます。

GraphQL__Client__OperationDefinition_70349176031380

ミューテーションまたはクエリを呼び出すときにオペレーション名を確実に使うには、クエリを定数に保存してください。

CreateOrUpdateTimePunchMutation = TimePunchCreation.query

この方法では、すべての Ruby モジュール名とクラス名を追加してオペレーション名を生成します。たとえば、次のようになります。

TimeBackend__ExportShiftBooking__CreateOrUpdateTimePunchMutation__CreateOrUpdateTimePunch

関連情報

詳しくは、GraphQL specification の Operation type and name をご覧ください。

 

このページは役に立ちましたか？