GraphQL in practice

    Suggestions will appear below the field as you type

    GraphQL in practice

      Suggestions will appear below the field as you type

      GraphQL in practice

      GraphQL in practice

      The SEEK API’s GraphQL endpoint is served over HTTPS. GraphQL is not tied to a certain programming language or client library; as long as you can make HTTP requests, you can integrate with the SEEK API.
      The SEEK API requires TLS 1.2  or newer, and does not support weak ciphers from TLS 1.0 and TLS 1.1.

      Operations

      The SEEK API supports two types of GraphQL operations: queries and mutations.
      • Queries allow you to read objects.
      • Mutations allow you to create, update and delete objects.
      This developer site provides guided examples of the queries and mutations relevant to each use case. A comprehensive lower-level listing is available in our schema documentation .
      The SEEK API does not make use of GraphQL subscriptions and instead provides webhooks.

      Requests and responses

      You can send any GraphQL operation that you see on this site or create in the Playground as an HTTP POST request. This works with any HTTP client that you already use and are familiar with.
      The SEEK API requires an application/json content type for HTTP POST requests to its GraphQL endpoint. It may support additional content types like application/graphql+json  once they have been stabilised in a GraphQL specification. The following examples also include tracing headers and a content localisation header.
      Response and request bodies in the SEEK API are encoded in UTF-8.
      A simple query can be bundled into a JSON request body like so:
      RequestResponse
      Copy
      POST https://graphql.seek.com/graphql HTTP/1.1
      Accept-Language: en-AU
      Authorization: Bearer PARTNER_TOKEN_HERE
      Content-Type: application/json
      User-Agent: example-application/1.2.3
      X-Request-Id: a9e3d78d-576d-470b-b1d2-52f4921be25c
      X-Session-Id: b5a8774c-c450-4906-a25c-861bce129106
      {
        "query": "{ version }"
      }

      Variables

      If your operation has arguments, they must be parameterised with variables. This is analogous to SQL prepared statements  and prevents code injection .
      RequestResponse
      Copy
      POST https://graphql.seek.com/graphql HTTP/1.1
      Accept-Language: en-AU
      Authorization: Bearer PARTNER_TOKEN_HERE
      Content-Type: application/json
      User-Agent: example-application/1.2.3
      X-Request-Id: 6837f359-0335-418c-80dc-9d98a57a330c
      X-Session-Id: b5a8774c-c450-4906-a25c-861bce129106
      {
        "query": "query($id: String!) { hiringOrganization (id: $id) { name } }",
        "variables": {
          "id": "seekAnzPublicTest:organization:seek:93WyyF1h"
        }
      }
      See the official GraphQL documentation  for more details.

      Optional arguments

      When an input argument is optional, GraphQL lets you omit it or set it to null:
      GraphQL
      CopyGraphQL Explorer
      # Inline arguments are only used to simplify these examples.
      # Parameterise your production queries as per advice above.
      

      # Recommended: omit unused argument
      query Omit {
        events(schemeId: "seekAnzPublicTest") {
          pageInfo {
            hasNextPage
          }
        }
      }
      

      # Not recommended: set unused argument to null
      query Null {
        events(schemeId: "seekAnzPublicTest", last: null) {
          pageInfo {
            hasPreviousPage
            hasNextPage
          }
        }
      }
      

      # Not recommended: create variable for unused argument
      query Variable($last: Int) {
        events(schemeId: "seekAnzPublicTest", last: $last) {
          pageInfo {
            ...PreviousPage
            hasNextPage
          }
        }
      }
      

      fragment PreviousPage on PageInfo {
        hasPreviousPage
      }
      While these options will seemingly produce an identical response from the SEEK API, your software should always omit unused options for two reasons:
      1. Changes to our GraphQL schema will be less likely to affect your software.
        Consider a scenario where your software does not use the last argument in the query above and it is deprecated from the SEEK API. If you already omit the argument, the deprecation will not impact your software. On the other hand, if you specify the argument and set it to null or a variable, you will have to manually update your software to remove it from your requests, which is pure busywork.
      2. Requests will be smaller and therefore faster.

      Selecting fields

      GraphQL provides your software with fine-grained control over which fields should be returned in a response. This allows clients to clearly express their requirements and the SEEK API to optimise responses by only providing the fields required.
      Your software should only select the fields it currently uses for three reasons:
      1. It allows SEEK to get a better understanding of your requirements.
        If we have an accurate view of your feature adoption, we can have more informed conversations about your integration and better accommodate your needs when considering future changes.
      2. Changes to our GraphQL schema will be less likely to affect your software.
        Consider a scenario where your software does not use the hasPreviousPage field in the query above and it is deprecated from the SEEK API. If you already omit the field, the deprecation will not impact your software. On the other hand, if you select the field, you will have to manually update your software to remove it from your requests, which is pure busywork.
      3. Requests and responses will be smaller and therefore faster.

      Tracing requests

      When an issue is found with an integration it’s sometimes difficult to determine which services were involved and how they interacted. SEEK has conventions for additional HTTP request headers to help trace issues across both our systems. These conventions should be used for all server-to-server HTTP requests including GraphQL queries, token requests and attachment file downloads. Some of these conventions should also be applied to requests made from the browser using browser tokens.
      • User-Agent  is a standard HTTP header identifying the service making an HTTP request.
        While your HTTP client library likely already sends a generic User-Agent, it’s recommended that you override this to include the name and version of the service making the request. This makes it easier to trace a request back to a specific deployment of your software when debugging an issue.
        Requests made from the browser do not need to alter this header.
      • The X-Request-Id header is a SEEK extension for tracing a request as it passes through our systems.
        It’s recommended that you generate a UUID  for each HTTP request and record that UUID along with any relevant log entries.
        Requests made from the browser should add this header.
      • The X-Session-Id header is a SEEK extension for grouping requests in the same interaction together. This helps isolate the sequence of events that led to an issue or error, especially for high traffic integrations.
        It’s recommended that you generate a UUID for each session and record that UUID along with any relevant log entries. You can choose which definition of session makes the most sense for you. For example, an interactive user flow for creating & posting a job ad might be assigned a single session. Or, every time your webhook endpoint is called you might generate a new session for all HTTP requests related to processing its events.
        Requests made from the browser should add this header.

      Example request

      HTTP
      Copy
      POST /graphql HTTP/1.1
      User-Agent: example-application-import-webhook/1.2.3
      X-Request-Id: 749fbdc9-fbe5-40e9-b5ae-fee3375f1e28
      X-Session-Id: 6eb0559a-cb91-4178-bb3d-9f5513e9ecc2

      Content localisation

      The SEEK API supports content localisation in select GraphQL operations and SEEK-hosted panels. It currently supports the following languages:
      Language
      Locale
      Australian English
      en-AU
      Bahasa Indonesia
      id-ID
      Thai
      th-TH
      As seen in the previous section, you may set the standard Accept-Language  HTTP request header to indicate the language preferences of the end user. A web browser will automatically set this header on client-side requests to the SEEK API that use a browser token, but you will need to manually propagate the preference for requests that originate from your software’s backend.
      The Accept-Language  header drives translations for user-facing response fields, such as copy for an interactive Job Posting feature like ad selection. The language(s) of the response may be described in the standard Content-Language  HTTP response header, falling back to Australian English (en-AU) where translations for the preferred languages are not available.
      Unsupported region subtags of a language will resolve to a supported subtag. For example, consider the following Accept-Language  header:
      HTTP
      Copy
      Accept-Language: en-US,th;q=0.9,
      While the SEEK API does not support the top preference in this header, US English (en-US), it will fall back to the associated primary language (en) and return content in Australian English (en-AU). This fallback is evaluated ahead of the second preference of Thai (th).

      Client libraries and tools

      While the SEEK API works fine with plain old HTTP clients, you can make the most of it with the GraphQL ecosystem.
      • GraphQL client libraries  make it easier to compose and run GraphQL operations.
        They are available in a variety of popular languages, including C#, Go, Java and JavaScript.
      • GraphQL code generators  automatically generate models and types in your language from the SEEK API’s schema.
        The SEEK API validates responses against its own schema at runtime, so you should never receive a non-conforming response.

      Request batching

      The SEEK API provides a couple of ways to batch multiple operations in a single request. This may be desirable to reduce HTTP overhead in certain scenarios, like processing a batch of events received via webhook.
      There are a couple of caveats, however:
      1. Higher response latency can be expected as a batch is constrained by its slowest operation.
      2. Operations are not processed atomically across the batch, so you’ll need to handle partial failures.

      GraphQL field-based batching

      GraphQL has built-in support for bundling multiple fields into a single operation:
      QueryVariablesResult
      CopyGraphQL Explorer
      query ($hirerId: String!, $jobCategoryId: String!) {
        # first query field
        hiringOrganization(id: $hirerId) {
          name
        }
      

        # second query field
        jobCategory(id: $jobCategoryId) {
          name
        }
      }
      This approach has the following characteristics:
      • Queries and mutations cannot be combined in a request.
      • Queries are executed concurrently.
      • Mutations are executed sequentially .
        This can be useful to avoid race conditions when applying multiple changes to an object, like updating both the contacts and status of a given position opening.
      • Broad support in GraphQL client libraries as it’s part of the specification .

      HTTP request-based batching

      The SEEK API also lets you pack multiple operations into the request body. The response body will contain an array of results in the same order.
      JSON
      Copy
      [
        {
          "query": "query($id: String!) { hiringOrganization (id: $id) { name } }",
          "variables": {
            "id": "seekAnzPublicTest:organization:seek:93WyyF1h"
          }
        },
        {
          "query": "query($id: String!) { jobCategory (id: $id) { name } }",
          "variables": {
            "id": "seekAnzPublicTest:jobCategory:seek:27HXTkNXh"
          }
        }
      ]
      This approach has the following characteristics:
      • Queries and mutations can be combined in a request.
      • Queries are executed concurrently.
      • Mutations are executed concurrently.
        This can be useful to speed up independent operations, like uploading two separate candidates.
      • Limited support in GraphQL client libraries.

      Request caching

      Some GraphQL client libraries support client-side caching and may even enable it by default. For example, the Apollo Client for JavaScript  prescribes an in-memory cache that assumes each object has a unique id or _id string field.
      Such heuristics may not work well with the SEEK API, which uses a non-primitive object identifier and various field names from the HR-JSON standard:
      JSON
      Copy
      {
        "profileId": {
          "value": "seekAnzPublicTest:candidateProfile:apply:7DtW6Q68gk2R4okNGhvg1Y"
        }
      }
      We recommend that you disable client-side caching for machine-to-machine requests. For requests that originate from a browser or mobile app, client libraries like Apollo Client may allow you to customise the cache , or turn it off:
      JavaScript
      Copy
      new ApolloClient({
        defaultOptions: {
          query: {
            fetchPolicy: 'no-cache'
          },
          watchQuery: {
            fetchPolicy: 'no-cache'
          }
        }
      });
      GraphQL: Mock objects
      GraphQL: SEEK API conventions