Documentation

Getting started with the Data API

In this article

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.

Robert van Boesschoten

Published: 29-04-2020

Last updated: 15-06-2020

General

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 id.

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

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

Setting up the GraphQL playground

The docs  and schema 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 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 store a username and password, and connect it to an Authentication Profile. 

For the examples, the following data model is used.


Make sure there is a relation between the Web user and the Role. The Web 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 table has his own set off permissions. Right now, GraphQL can only fetch data. The read permission is used to configure who has access via the GraphQL query.

After that, create a record containing a username and password to be used in the actual Login.

Login

You can login via the mutation login by providing a Betty Blocks authentication profile UUID, the username and password. The response will contain your JWT token.

Query

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

Response

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


Example


Authorization in the Playground

So now we performed our first login, got the authorization JWT token and are ready to use the playground. Using this token in our request will enable features like `docs` and `schema`.

Add the following JSON snippet to the HTTP Headers section:

{
  "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 datamodel's structure, used in the `docs` and `schema` features.

Examples

`Docs`


`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 here!

In this article