Best practices for GraphQL clients

Best practices for developing quality APIs at Indeed.

 

As a GraphQL client, follow these best practices.

Request only the data that you need

GraphQL enables clients to request exactly the data that they need.

Do not request all, or a predefined set of, fields that your client does not use.

With GraphQL, Indeed can observe the usage of fields. If clients request fields that they don't use, this interferes with our analytics and makes it harder to determine whether to deprecate a field.

Give your GraphQL operations unique, descriptive names

GraphQL enables you to name operations with a descriptive name. Use Pascal case in your descriptive names.

Self-documenting operation names communicate the meaning and context of your API to service implementers, which is powerful information, especially during schema changes.

Make sure to understand how operation naming works with GraphQL client libraries. When not used properly, libraries can give each invocation of the same named operation a dynamic unique name, which has a negative impact on observability capabilities.

Recommended

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

Not recommended

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

Use variables for arguments in GraphQL requests

A GraphQL client can use variables to substitute different values for a literal in an operation.

Variables enable reuse of client-defined operations.

Back-end systems benefit because GraphQL servers parse and validate each permutation, and prevent caching.

Clients can reuse operation definitions and avoid costly recreation of the operation. Clients can represent operation definitions in a clear and straightforward manner. Variables make it simple to avoid mishandling of personally identifiable information (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

To ensure the use of an operation name when you invoke a mutation or query by using Ruby on Rails, store the query in a constant.

For example, if you invoke a mutation as follows:

<OperationName>{ variables....} 

The operation does not necessarily appear with the <OperationName> name on Apollo Studio.

Internally, the library stores the mutation in a Ruby constant. If not, it dynamically allocates a name to it, such as:

GraphQL__Client__OperationDefinition_70349176031380

To ensure the use of an operation name when you invoke the mutation or query, store the query in a constant:

CreateOrUpdateTimePunchMutation = TimePunchCreation.query

This action appends all Ruby module names and class names and generates an operation name. For example:

TimeBackend__ExportShiftBooking__CreateOrUpdateTimePunchMutation__CreateOrUpdateTimePunch

See also

For details, see Operation type and name in the GraphQL specification.

 

Was this page helpful?