GraphQL クライアントのベストプラクティス
Indeed の API を呼び出す GraphQL クライアントを構築するためのベストプラクティスです。
Indeed の API を呼び出す GraphQL クライアントを構築するときは、次のベストプラクティスに従ってください。
必要なデータだけをリクエストする
#クライアントが使用するフィールドだけをリクエストしてください。
Indeed は、フィールドを非推奨にしても問題ないかを判断するために、フィールドの利用状況を追跡しています。使用しないフィールドをリクエストすると、このデータが不正確になります。
GraphQL オペレーションに一意で分かりやすい名前を付ける
#すべてのオペレーションに、Pascal case で名前を付けてください。
分かりやすい名前は、各オペレーションの目的を Indeed に伝えます。これは、特にスキーマ変更時に重要です。
ご利用のクライアントライブラリがオペレーション名をどのように扱うかを確認してください。ライブラリによっては、呼び出しのたびに異なる名前を自動生成するため、オペレーションを追跡しにくくなります。
推奨
#query FetchJobForHomepageModal($id: ID) { job(id: $id) { result { title } }}非推奨
#query($id: ID) { job(id: $id) { result { title } }}GraphQL リクエストの引数に変数を使用する
#引数の値は、オペレーションに直接記述せず、変数として渡してください。
変数を使用 すると、1 つのオペレーション定義を再利用でき、定義を読みやすく保てます。また、個人を特定できる情報（PII）をオペレーションのテキストに含めずに済みます。
変数はサーバーにも役立ちます。サーバーは1つのオペレーションをキャッシュし、どの引数値にも再利用できます。変数を使用しない場合、サーバーはオペレーションのバージョンごとに解析と検証を行う必要があります。
推奨
#query SurveyAnswers($input: QuestionAnswersInput) { questionAnswers(input: $input) { result { answerId answerText } }}変数
#{ "input": { "questionId": 124324, "answers": [] }}非推奨
#query SurveyAnswers { questionAnswers(input: { questionId: 124324 answers: [] }) { result { answerId answerText } }}標準のエラーコードを処理する
#Indeed の API は次の標準のエラーコードを返すため、クライアントは API が異なっても、各エラーコードを同じ方法で処理できます。
| エラーコード | 説明 |
|---|---|
BAD_USER_INPUT | 入力値が無効です。標準の GraphQL の非null チェックと型チェックを超える検証が対象です。 |
FORBIDDEN | 認証情報は有効ですが、このクエリまたはミューテーションは許可されていません。HTTP 403 Forbidden に相当します。 |
INTERNAL_SERVER_ERROR | サーバーで予期しない障害が発生しました。 |
QUERY_TOO_COMPLEX | クエリが 1 回のリクエストで許可される複雑さを超えています。 |
QUERY_TOO_NESTED | クエリのネストの階層が多すぎます。 |
UNAUTHENTICATED | リクエストに有効な認証情報がないため、サーバーはリクエストを実行しませんでした。HTTP 401 Unauthorized に相当します。 |
Ruby on Rails クライアント
#Ruby on Rails では、各クエリを定数に保存してください。クライアントライブラリは、その定数からオペレーション名を生成します。
オペレーションをインラインで呼び出すと、ライブラリは記述した名前を無視して、次のような名前を生成します。
GraphQL__Client__OperationDefinition_70349176031380代わりに、クエリを定数に保存します。
CreateOrUpdateJobMutation = JobClient.parse(<<~GRAPHQL) mutation CreateOrUpdateJob(...) { ... }GRAPHQLライブラリは、モジュール名、クラス名、定数名からオペレーション名を生成します。
MyApp__JobSync__CreateOrUpdateJobMutation__CreateOrUpdateJobリファレンス
#- Operation type and name （新しいウィンドウで開きます） — GraphQL オペレーションに名前を付ける方法を説明します。
- Variables （新しいウィンドウで開きます） — GraphQL オペレーションに値を渡す方法を説明します。
- OWASP Web Security Testing Guide （新しいウィンドウで開きます） — Web アプリケーションのセキュリティテストについて説明します。