Data API reference

Reference to data API queries, sorting, filtering, pagination, access tokens, API limits and rate limiting.

Data API allows you to retrieve and manipulate data from your Betty Blocks applications. This article covers querying properties and model relations, setting up sorting, filtering, pagination, etc. Additionally, it includes details on access tokens, API limits, and how requests are managed using buckets.

Connecting to GraphQL playground

Once you’ve set up a connection with the GrapghQL playground as explained in Getting started with data API, you can start querying data.

The GraphQL playground offers a comprehensive list of available queries (see more), but this article will focus on practical examples using a Task model. Adapt these examples to your models as necessary.

Note: Connecting through the playground will also give you an entire list of queries available. Our interest here is querying data from the Task model.

Querying data

Get all tasks

This query returns an overview of all Task records, retrieving the IDs, names and end dates.

{
    allTask {
        results {
            id
            name
            endDate
        }
    }
}

Output example:

Filtering tasks with a 'where' condition

Use filters to narrow down the results. The following example retrieves tasks where the ID is either 3 or 4.

{
    allTask(where: { id: { in: [3, 4] } }) {
        results {
            id
            name
            endDate
        }
    }
}

Output example:

Retrieve a single task

This query returns task 10 which matches the provided filter.

{
    oneTask(where: { id: { eq: 10 } }) {
        id
        name
        description
    }
}

Output example:

Sorting and pagination

Sorting tasks by a specific field

You can order the results by a specific field in ascending (ASC) or descending (DESC) order. The following query sorts tasks by id in descending order.

{
    allTask(sort: { field: id, order: DESC }) {
        results {
            id
        }
    }
}

Pagination

To retrieve data in chunks, you can use pagination options like limit and offset. For example, the following query retrieves the first 5 tasks:

{
    allTask(limit: 5, offset: 0) {
        results {
            id
            task
        }
    }
}

Querying relational data

You can retrieve related data along with the main task. In the following example, a task is fetched along with its associated project details (Task model is related to Project model)

{
  oneTask(where: { id: { eq: 3 } }) {
    id
    name
    project {
      name
    }
  }
}

Output example:

Note: Ensure that authorization on relational data is properly set. If not, an 'Unauthorized' error may occur.

Handling different data types

The following query demonstrates how to retrieve records that include file property values, such as name and URL.

{
    allArtists {
        results {
            name
            songs {
                art {
                    name
                    url
                }
            }
        }
    }
}

Access tokens

Requesting data through the data API can be available to everyone (public data) or only to authorized users (private data). For the second group, a valid access token is required. With the refresh token flow for the data API, users can extend their active sessions, instead of starting a new one.

Refresh token

The login mutation has been updated to return a refreshToken:

mutation login{
     login(
      authProfileUuid: "<authProfileUuid>"
      username: "<username>", 
      password: "<password>", 
     ){
         isValid
         jwtToken
         refreshToken
   }
}

This token can be used in a new mutation refreshToken to extend your login by returning a new access JWT token. Be aware, that for security reasons the refresh token can only be used once, and the user will receive a new one after the mutation has been completed:

mutation refresh{
        refreshToken(
        token: "<refreshToken>"
    ){
           isValid
           jwtToken
           refreshToken
           refreshExpiresIn
   }
}

Revoking a token

A refresh token can be also revoked at any time, using the revokeRefreshToken mutation:
​

mutation revoke{
         revokeRefreshToken(
         token: "<refreshToken>"
     ){
           removed
           refreshId
      }
}

Maximum and minimum token lifetimes

• Access token

  • Maximum lifetime = 10800 seconds (3 hours)

  • Minimum lifetime = 60 seconds (1 minute)

• Refresh token

  • Maximum lifetime = 1209600 seconds (336 hours, 14 days)

  • Minimum lifetime = 60 seconds (1 minute)

You can adjust token lifetimes in the Authentication profiles settings, but you cannot exceed the maximum values.

Limits on data API

To ensure smooth operation, there are limits in place for the data API:

• Read request rate:

  • Production: 200 per minute

  • Non-production and sandboxes: 100 per minute

• Database query timeout: 5 seconds

• Maximum queries per request: 10 queries

• Maximum nesting: 4 layers

Rate limiting and buckets

Rate limiting counts the requests made to our server and applies a method called 'count' to determine when to block further requests. Both read and write requests are counted, and each application or sandbox has its own limit.

Buckets

To count and check the amount of requests you make, and to make sure applications don't make too many, they are being collected in something called a bucket. Multiple buckets handle a separate limit for a specified time.

In the new setup, 3 buckets are defined; one with a refresh rate per minute, one with an hourly refresh rate, and one with a daily refresh rate:

• 1-minute bucket: 200 requests

• 1-hour bucket: 2600 requests

• 1-day bucket: 1150 requests

Requests are first taken from the 1-minute bucket. If it’s empty, the hourly or daily bucket is used. Buckets refresh automatically when their time limit expires.

Note: In sandbox applications, these limits will be divided by 2. The reason for this is that sandboxes are more likely to contain inefficient pages and are used to test new code setups, which can slow down the server.