Best practices for GraphQL clients

Best practices for building GraphQL clients that call Indeed APIs.

 

Follow these practices when you build a GraphQL client for Indeed APIs.

Request only the data that you need

Request only the fields your client uses.

Indeed uses field usage to decide when a field is safe to deprecate. Unused fields in your requests skew that data.

---

Give your GraphQL operations unique, descriptive names

Name every operation in Pascal case.

Descriptive names show what each operation does. That helps most when the schema changes.

Check how your client library names operations. Some libraries generate a new name for each call, which makes operations hard to track.

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

Pass argument values as variables, outside the operation text.

Variables let you reuse one operation, keep it readable, and keep personally identifiable information (PII) out of the operation text. The server can cache that operation and reuse it for any argument values. Without variables, the server parses and validates every version.

Recommended

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

Variables

{
  "input": {
    "questionId": 124324,
    "answers": []
  }
}

Not recommended

query SurveyAnswers {
  questionAnswers(input: {
    questionId: 124324
    answers: []
  }) {
    result {
      answerId
      answerText
    }
  }
}

---

Handle standard error codes

Indeed APIs return these error codes. Handle each code the same way for every API.

Common error codes

Error code	Description
BAD_USER_INPUT	An input value is invalid. Covers validation beyond the standard GraphQL non-null and type checks.
FORBIDDEN	The credentials are valid but don't allow this query or mutation. Equivalent to HTTP 403 Forbidden.
INTERNAL_SERVER_ERROR	The server failed unexpectedly.
QUERY_TOO_COMPLEX	The query is more complex than one request allows.
QUERY_TOO_NESTED	The query has too many nested levels.
UNAUTHENTICATED	The request doesn't have valid credentials, so the server didn't run it. Equivalent to HTTP 401 Unauthorized.

---

Ruby on Rails clients

In Ruby on Rails, store each query in a constant. The client library builds the operation name from that constant.

An inline call ignores the name you wrote. The library generates a name such as:

GraphQL__Client__OperationDefinition_70349176031380

Store the query in a constant instead:

CreateOrUpdateJobMutation = JobClient.parse(<<~GRAPHQL)
  mutation CreateOrUpdateJob(...) {
    ...
  }
GRAPHQL

The library then builds the operation name from the module, class, and constant names:

MyApp__JobSync__CreateOrUpdateJobMutation__CreateOrUpdateJob

---

References

• Operation type and name (opens in a new window) — Explains how to name GraphQL operations.
• Variables (opens in a new window) — Explains how to pass values to GraphQL operations.
• OWASP Web Security Testing Guide (opens in a new window) — Web application security testing guidance.

 

Was this page helpful?