This is the place for all the know-how, tips, and tricks to start working with the Data API. From setting up the basics to authentication and executing queries, keep reading to find out.

To get started with the Data API, we will have to touch on these subjects:

Data API's playground
Preparing the Data model
Preparing an Authentication profile
Login mutation from the playground
Authorization in the playground

Data API's playground

The Data API can be accessed via the URL below. The <identifier> is the unique URL part of your application and <app_uuid> can be replaced by the Betty Blocks application UUID.

https://<identifier>.betty.app/api/runtime/<app_uuid>

This URL will open the GraphQL playground, a place where all queries and mutations can be tested.

Setting up the GraphQL playground

The Playground docs and schema on the right-hand side will offer an overview of your options, but will not work out of the box. The Playground needs a valid Authentication token to enable all these features. We need to create a JWT access token by calling the Login mutation.

Preparing the Data model

Before we can perform the Login mutation, we need to prepare our Data model in order to create a new user record that stores a username and password and connect it to an Authentication Profile. We will first prepare the Data model.

Make sure there is a relation between the model where the end-users of the Application are stored and the Role model. The logged-in user needs to have a Role assigned in order to configure the authorization! This relation needs to be a Has and Belongs to Many! Otherwise, you will receive a 500 Internal Server Error when you run some GraphQL queries.

Each model has its own set of permissions. Right now, the Data API is mainly focused on fetching data. The read permission on each model is used to configure who has access and who hasn't.

In the example above, we have attached 3 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. I hear you thinking "why would you have so many models to store end-users in?". This strongly depends on how you would like to authenticate those end-users. In this example are:

End-users stored in the WebUser model authenticated via Username/Password
End-users stored in the Partner model authenticated via Google SSO
End-users stored in the User model authenticated via Betty Blocks login

When you have your end-user's model connected to the existing Role model, you can create a new record containing a username and password (if the authentication method is username/password of course) to be used in the actual login mutation. You can create this new record either via the Page Builder or via the Back office.

Preparing an Authentication Profile

When the Data model preparations 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.

Make sure you creating a new Authentication profile based on the model where your users are stored. Whit the Data model and Authentication profile 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>"
    }
  }
}

Example

Authorization in the playground

So now we performed our first login, got the access and refresh tokens and are ready to use the playground. Using the access token in our request will enable features like docs and schema 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 and schema features.

Playground docs

Playground schema

Now you got the basics working, we're able to start querying our data. This is somewhat the same as we did for the Login, but with its own purposes. We're covering that subject in this article!

➝ Next article: Data API queries