Query

The query type defines how GraphQL operations read data. Queries are sent to the service URL using an HTTP request where the request body will specify what data to retrieve. It is analogous to performing HTTP GET using the REST API, but sent using the POST method.

The main entry point for queries are the root level connections, which allow lists of 4me records to be accessed using pagination. The root level has fields that expose 4me object identifiers in a GraphQL standardized way.

A query request to the 4me GraphQL API must indicate which connection should be queried, how many records should be retrieved at most, and which fields of those records. An example requests query retrieving the subject, and name of the requestor, of the first 10 requests:

  query {
    requests(first: 10) {
      nodes {
        subject
        requestedFor {
          name
        }
      }
    }
  }

To execute this query it should be send with the POST method to the service URL adding the Authorization and X-4me-Account headers for the token and current account respectively. The token used must allow 'Read' access on the 'Request' model.

Note: even though the requestedFor field accesses 'Person' records no explicit access to the 'Person' model is required in this case. If more details of the requested for person are queried then it is required to have the scope 'Read' access on the 'Person' model.

More useful queries include filters to select which records to return. To this end one should add a filter argument to the connection. Each connection at the root level has its own GraphQL type describing possible filter options. For requests the available filter options are specified by the RequestFilter, for changes the ChangeFilter is available, etc.

An example request using a filter to only return open requests using the free format query sales could look like:

  query {
    requests(
      first: 10,
      filter: {
        query: "sales",
        status: {
          values: ["completed"],
          negate: true
        }
      }
    ) {
      nodes {
        subject
        requestedFor {
          name
        }
      }
    }
  }

Fields

Fields access a single value, or an array of values, of an object. The following fields are exposed at the root level where the 4me GraphQL API exposes node identifiers in a standardized way, allowing clients to elegantly handle caching and data refetching.

A sample query using the node field (retrieving the name of a person based on id) would be:

  query {
    node(id: "NG1lLmNvbS9QZXJzb24vNg") {
      ... on Person { name }
    }
  }

In this case an inline fragment is used to indicate that although the query uses the generic node field, which is typed to return a Node, we know it will retrieve a Person. This means the query can return the name field defined by the Person type.

me (Person!)

The currently authenticated person.

node (Node)

Returns a single record by ID.

Argument Type Description
id ID!

ID of the record.

nodes ([Node]!)

Returns a list of records by IDs.

Argument Type Description
ids [ID!]!

IDs of the records.

rateLimit (RateLimit!)

The rate limit status.

Connections

Connections allow lists of records to be accessed using pagination. When retrieving a connection either a first or last argument must be supplied to indicate the upper limit on the number of rows returned. The maximum number of records that can be retrieved per connection in a single request is 100.

Each 4me record type has its own root connection which allows it to be queried.