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 tracks field usage to decide when a field is safe to deprecate. Requests for fields you don't use skew that data.

---

Give your GraphQL operations unique, descriptive names

Name every operation in Pascal case.

Descriptive names tell Indeed what each operation is for, which matters most when the schema changes.

Check how your client library handles operation names. Some libraries give each call a different generated name, which makes your 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 instead of writing them into the operation.

With variables, you can reuse one operation definition, keep it readable, and keep personally identifiable information (PII) out of the operation text.

Variables also help the server. It can cache one operation and reuse it for any argument values. Without variables, the server must parse and validate every version of the operation.

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 standard error codes, so your client can handle each one the same way across APIs.

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.

If you call an operation inline, the library ignores the name you wrote and generates one, 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?