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

Indeed の API を呼び出す GraphQL クライアントを構築するためのベストプラクティスです。

 

GraphQL クライアントを構築するときは、次のベストプラクティスに従ってください。

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

GraphQL では、クライアントは必要なデータだけを正確にリクエストできます。ご利用のクライアントが使用しないフィールドは、リクエストしないでください。

Indeed は、フィールドを非推奨にしても問題ないかを判断するために、フィールドの利用状況を追跡しています。使用しないフィールドをリクエストすると、このデータが不正確になります。

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

すべてのオペレーションに名前を付け、Pascal case を使用してください。

分かりやすい名前は、オペレーションの意味とコンテキストをサービス実装者に伝えます。これは、特にスキーマ変更時に重要です。

ご利用のクライアントライブラリがオペレーション名をどのように扱うかを確認してください。ライブラリによっては、同じオペレーションを呼び出すたびに一意の動的な名前を割り当てるため、可観測性が低下します。

推奨

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

非推奨

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

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

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

変数を使用すると、オペレーション定義を再作成せずに再利用でき、定義を読みやすく保てます。また、個人を特定できる情報（PII）の不適切な取り扱いも避けられます。

変数はサーバーにも役立ちます。変数を使用しない場合、GraphQL サーバーはオペレーションの値の組み合わせごとに解析と検証を行い、キャッシュできません。

推奨

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 を使用するときは、列挙攻撃につながる情報を公開しないようにしてください。
INTERNAL_SERVER_ERROR	サーバーで予期しない障害が発生し、レスポンスを返せません。サーバーで処理できない障害にだけ、この汎用エラーを使用します。
QUERY_TOO_COMPLEX	クエリが 1 回のリクエストで許可される複雑さを超えています。
QUERY_TOO_NESTED	クエリにネストが多すぎます。
UNAUTHENTICATED	リクエストに十分な認証資格情報がないため、サーバーはクエリ、ミューテーション、またはフィールド解決を実行しません。このエラーコードは、HTTP 401 Unauthorized に相当する GraphQL のエラーコードです。

Ruby on Rails クライアント

Ruby on Rails では、クエリを Ruby の定数に保存してください。クライアントライブラリは、その定数からオペレーション名を取得します。

ミューテーションをインラインで呼び出すと、記述した名前が Apollo Studio に表示されるとは限りません。

<OperationName>{ variables....}

ライブラリは、代わりに動的な名前を割り当てます。

GraphQL__Client__OperationDefinition_70349176031380

クエリを定数に保存します。

CreateOrUpdateTimePunchMutation = TimePunchCreation.query

ライブラリは、すべての Ruby モジュール名とクラス名を追加してオペレーション名を生成します。

TimeBackend__ExportShiftBooking__CreateOrUpdateTimePunchMutation__CreateOrUpdateTimePunch

リファレンス

• Operation type and name （新しいウィンドウで開きます）
• Variables （新しいウィンドウで開きます）
• OWASP Web Security Testing Guide （新しいウィンドウで開きます）.

 

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