GraphQLクライアントのベストプラクティス
Indeedで高品質なAPIを開発するためのベストプラクティスです。
GraphQLクライアントとして、次のベストプラクティスに従ってください。
必要なデータだけをリクエストする
GraphQLでは、クライアントは必要なデータだけを正確にリクエストできます。
クライアントが使わないすべてのフィールドや、事前定義したフィールドセットをリクエストしないでください。
GraphQLでは、Indeedはフィールドの利用状況を把握できます。クライアントが使わないフィールドをリクエストすると、分析の妨げになり、フィールドを非推奨にするべきかどう かを判断しにくくなります。
GraphQL operationに一意で分かりやすい名前を付ける
GraphQLでは、operationに分かりやすい名前を付けられます。名前にはPascal caseを使用してください。
self-documentingなoperation名は、APIの意味とcontextをservice implementerへ伝えます。これは、特にschema変更時に有用です。
GraphQL client libraryでoperation namingがどのように機能するかを理解してください。適切に使わないと、libraryが同じ名前のoperationを呼び出すたびに動的な一意名を付けることがあり、observabilityへ悪影響を与えます。
Recommended
query FetchJobForHomepageModal($id: ID) { job(id: $id) { result { title } }}Not recommended
query($id: ID) { job(id: $id) { result { title } }}GraphQL requestの引数にvariablesを使用する
GraphQLクライアントは、variablesを使用して、operation内のliteralへ異なる値を代入できます。
variablesを使うと、クライアントが定義したoperationを再利用できます。
back-end systemにとっても利点があります。GraphQL serverはそれぞれのpermutationをparseしてvalidateするため、cachingを妨げるからです。
クライアントはoperation definitionを再利用できるため、costの高いoperationの再作成を避けられます。また、operation definitionを明確で分かりやすく表現できます。variablesを使うと、個人を特定できる情報であるPIIの不適切な取り扱いも避けやすくなります。
Recommended
query SurveyAnswers($questionId: QuestionAnswersInput) { questionAnswers(input: $questionId) { result { answerId answerText } }}Variables
{ questionId: 124324}Not recommended
query SurveyAnswers { questionsAnswers(input: { questionId: 124324 }) { result { questionId answerId answerText } }}Ruby on Rails clients
Ruby on Railsを使用してミューテーションまたはクエリを呼び出すときにoperation nameを確実に使うには、queryをconstantへ保存してください。
たとえば、次のようにミューテーションを呼び出す場合です。
<OperationName>{ variables....} operationは、Apollo Studio上で必ずしも<OperationName>という名前では表示されません。
libraryは内部でミューテーションをRuby constantへ保存します。そうしない場合は、次のような名前を動的に割り当てます。
GraphQL__Client__OperationDefinition_70349176031380ミューテーションまたはクエリを呼び出すときにoperation nameを確実に使うには、queryをconstantへ保存してください。
CreateOrUpdateTimePunchMutation = TimePunchCreation.queryこの方法では、すべてのRuby module名とclass名を追加してoperation nameを生成します。たとえば、次のようになります。
TimeBackend__ExportShiftBooking__CreateOrUpdateTimePunchMutation__CreateOrUpdateTimePunchSee also
詳細は、GraphQL specificationのOperation type and nameをご覧ください。