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 R-Service records to be accessed using pagination. The root level has fields that expose R-Service object identifiers in a GraphQL standardized way.
A query request to the R-Service 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 workflows the WorkflowFilter 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 R-Service 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.
Account!)
The current account.
AttachmentStorage!)
Details on how to upload files to the R-Service attachment storage facility.
Person!)
The currently authenticated person.
[Node]!)
Returns a list of records by IDs.
| Argument | Type | Description |
|---|---|---|
ids |
[ID!]!
|
IDs of the records. |
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 R-Service record type has its own root connection which allows it to be queried.
Each root connection has a view argument which defaults to current_account. Note that the user interface
usually defaults to all.