Introduction

ROQ Suite uses GraphQL as the main approach for representing APIs. GraphQL is simple to use and is easy to learn. We recommend that you start your journey at the official GraphQL documentation: 📖 Introduction to GraphQL.

ROQ Suite consists of a headless Feature-as-a-Service system called ROQ Platform and, optionally, an open source kickstarter boilerplate called ROQ One. Both applications provide an API that is based on GraphQL. We recommend that you familiarize yourself with GraphQL if you want to query the API and interact with either ROQ Platform or ROQ One Backend.

Step by step tutorial: how to connect

We recommend users try out the GraphQL API directly before implementing it in code. You can retrieve data using a simple query like this:

query{
  users{
    data{
      id
      email
    }
  }
}
GRAPHQL

API of ROQ Platform

Before you can run this query against ROQ Platform's GraphQL API, you need to conduct some preparations.

First, you must find the URL of ROQ Platform, which could be something similar to: https://saturn-pp.roq-platform.com. It’s important to know that ROQ Platform exposes two endpoints (called “graph” in GraphQL terminology). You can read more about this here: https://docs.roq.tech/dev/authentication  To try out the API, we recommend using the client-side API: /v01/graphql The full URL could look like this:

https://saturn-pp.roq-platform.com/v01/graphql
CODE

Now you need to select a tool. If you are new to GraphQL, then take a look at the simple-but-powerful API client Insomia

Now you are ready for your first query. Just create a new request, select POST as the method, and select GraphQL like this:

When you send this query, you should see a INVALID_TOKEN error. That means the connection to ROQ Platform was successful but requires authentication (see Authentication for more details).

To fetch data, you need to obtain a valid JWT token and send it as an HTTP header called roq-platform-authorization:

There a several ways to get a token. The most straight-forward method is to login to your application and get the roq-platform-authorization token from the header of the GraphQL queries sent to ROQ Platform. This can be seen in the screenshot below. Here, it is important that the user has sufficient permissions (see Access management for more information).

To show the GraphQL queries, you will use a Chrome-extension called ➚GraphQL Network Inspector

With the token in place, you can now retrieve a list of users from ROQ Platform:

Troubleshooting: If only an empty list is returned after running this command, check in console to determine whether any users have been synchronized to ROQ Platform. If there are users but you cannot fetch them, then check the permissions of the user that you created to generate the token.

API of ROQ One Backend

Fetching data from ROQ One Backend generally follows the same procedure. You should already know the URL for your own backend. Again, you will need a token which you can get from your application. If using ROQ One, then you will need to find a query against ROQ One Backend and look for the authorization header:

With this header you can then perform queries against your own GraphQL API. 

Note: If you have public endpoints, then the token may not be required.