Development Guides
GraphQL Basics API

GraphQL basics

Introduction

GraphQL is simple to use and easy to learn. We recommend starting your journey at the official GraphQL documentation: Introduction to GraphQL (opens in a new tab). This page explains the basic concepts of fetching data using ROQ Platform.

Queries and mutations

In GraphQL terminology there are two main terms:

  • Query - A query is way to load data from ROQ Platform
  • Mutation - A mutation is way to change (~mutate) data

Fetch by ID

You can always fetch any record by the ID like this:

await client.asSuperAdmin().user({ id: '123' })

Adding relations

GraphQL empowers the client to define exactly how the data should be returned. In the example below, a user is fetched including the names of all the related user groups.

await client.asSuperAdmin().user({ id: '123', withUserGroups: true })

Counting

When you use a plural query (files, users, ...), then you can always ask for the total count.

const response = await client.asSuperAdmin().users();
const { totalCount } = response.users;

Order, Limit and Offset

If you'd like to show the data in a table, you can use the API's advanced functionality with these parameters: limit, offset and sort.

await client.asSuperAdmin().users({
  limit: 10,
  offset: 1,
  order: {
    order: 'ASC',
    sort: 'email',
  },
})
ParameterTypeDescription
limitnumberLimits the number of returned records
offsetnumberSkips records (useful for pagination)
orderobjectDefines order (either ASC or DESC) and the ordered field

Filtering of data

The filter object enables you to apply advanced filters on all fields. For instance the following query returns only active users.

await client.asSuperAdmin().users({
  filter: {
    active: {
      equalTo: true,
    },
  },
})