After reading this article, you’ll know:

How to access and set up the GraphQL playground
How to prepare your models to organize your data
Steps to create an authentication profile for secure API access
How to perform a login mutation using the GraphQL playground

Welcome to your go-to guide for getting started with the data API. In this article, we’ll cover everything you need to know, from setting up the basics to mastering authentication and executing queries. Whether you’re just starting or looking to refine your approach, you’ll find all the essential tips and tricks right here.

Accessing GraphQL playground

To set up the environment for working with data API, you need to reach the GraphQL playground. Go to Actions and pick up any of the existing actions from the overview, then find Test run > Playground > Go to playgound.

GraphQL playground is the space where all queries and mutations can be tested.

Playground Docs on the left-hand side will offer an overview of your options. However, this feature won't display items out-of-the-box. The playground needs a valid authentication access token to enable all these features.

Further, we'd need to create a JWT access token by calling the login mutation.

Access token grants you to access certain data (based on the roles and permissions of your application). A refresh token is used to request a (new) access token. Retrieving your JWT access token via the login mutation is covered further in the article.

Note: You may encounter a 'PDM error' while using the playground at first. Make sure you've used the PDM login button to log in as an admin builder in such case!

Preparing models

Before executing the login mutation, we must prepare the Models. Start by ensuring an end-user record model (e.g. Webuser) stores a username and password (Email & Password properties), which will be linked to an authentication profile.

Next, set up a relation between the model where the end-users are stored and the Role model. The logged-in user must have a role assigned to configure authorization properly. The relations should be set as Has and belongs to many; otherwise, running certain GraphQL queries may result in a 500 Internal Server Error.

Each model comes with its own set of permissions. Currently, the data API is primarily focused on data retrieval. You’ll need to configure the Read permission for each model to determine who has access and who doesn’t.

Relations with Role model

In the example below, we have attached three different models to the Role model. The reason why is to showcase what every model your end-users are stored into, it should always have a relation with the Role model.

You might wonder, “Why have multiple models to store end-users?” The answer depends on how you want to authenticate those users. Here we have the following models:

Webuser: End-users are authenticated via Username/password
Partner: End-users are authenticated via Google SSO
User: End-users are authenticated via Betty Blocks login

Once your end-user model is linked to the existing Role model, you can create a new record with a username and password (if using Username/password authentication) to be used in the login mutation.

Preparing an authentication profile

When the preparations in Models are done, we can continue to configure an authentication profile. This profile describes how your users should be authenticated. Make sure you have created your profile based on the Username / password kind.

With the data models and authentication profiles in place, we are ready to continue with the actual login mutation in the data API's playground.

Login mutation via the playground

You can log in via the mutation login by providing a Betty Blocks authentication profile UUID, username and password. The response will contain the access token and/or refresh token value.

Mutation

mutation login {
  login(
    authProfileUuid: "<auth-profile-uuid>", 
    username: "<username>", 
    password: "<password>"
  ) {
    jwtToken
    refreshToken
  }
}

Response

{
  "data": {
    "login": {
      "jwtToken": "<your-jwt-token>", 
      "refreshToken": "<your-refresh-token>"
    }
  }
}

Authorization in the playground

So now we performed our first login, got the access and refresh tokens, everything is ready the playground use. Using the access token in our request will enable features like Docs, History and Explorer in the playground. Add the following JSON snippet to the (HTTP) Headers section in the playground at the bottom left.

{
  "Authorization":"Bearer <jwt-token>"
}

Run again, refresh the playground, and all features will be at your disposal. This login was required to connect with our application's meta-data to collect its data model's structure, used in the Docs.

Now you got the basics working, we're able to start querying our data. Find more examples of data API uses in the Data API reference article.

Betty Blocks data API

Triggering actions via an API call

Creating an iManage integration

Using OAuth 2.0 to set up Google SSO for your application

Data API reference