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.