Group 65Go to Betty Blocks
All Collections
Platform API and Custom API
Platform API explained
Betty Blocks REST API

Betty Blocks REST API

In this article, you'll learn how to request the Betty Blocks REST API to receive data in JSON formatting.
Ralph Duin avatar
Written by Ralph Duin
Updated over a week ago

The Betty Blocks API provides you with an easy way to communicate with your application from another Betty Blocks application or external application. This article is meant to show you the possibilities of the API.

After reading this article, you'll know:

  • How you can get your API authentication
  • Which requests you can do with the API
  • How you can start using the Betty Blocks API
  • What HTTP Status Codes are and what they mean

Authentication

The Betty Blocks API is protected with HTTP basic authentication. You will need a username and API key for API access. You can generate an API key for a user in the app in the users overview of your application in My Betty Blocks. To get there quick you can go to Tools → User management in the Builder Bar.

Generating a key

Generate an API key for an existing user in your app by clicking the API button on a user, seen in the animation below.

Beware! An API key can only be seen once! When you click the API button, an API key will be given to you, so make sure to copy this to your clipboard or any other (temporary) place because you won't be able to view it again.

API User

You can also choose to create an API user. You can add a random (non-existing) email address as a user in your app and generate an API key for that user. This way you're not dependent on the specific, existing user. If you remove the user from your app, all the API calls authenticated with that user's API key will stop working.

Example: api-user@domain.com

Once you've generated an API key, you can authenticate your requests with HTTP Basic authentication, where the username is the API user's email address and the password is the generated API key.

Removing API access

When a user's API access needs to be revoked, just click the API button again in the User Management overview and the API key will be removed. 

Possible data requests

The Betty Blocks API uses HTTP requests to perform CRUD-based actions. CRUD stands for Create, Read, Update and Delete, or for HTTP requests: POST, GET, PUT and DELETE.

  • The HTTP verb POST is used to create new resources. REST does not specify how the data is sent, it posts new records and expect the server to provide the appropriate location URI for the new resource. Your POST can only create 1 record (you will have to send multiple POST requests to create multiple records).
  • The HTTP verb GET is used to list or retrieve resources. For collections, the service should return an array of items that are members of the collection. These can be the full details, or just information on where to find the additional data about each resource.
  • The HTTP verb DELETE is used to delete resources. If a collection URI is specified, the whole collection should be deleted. If an element URI is specified, just that specific item should be deleted. Recommended is creating a boolean on a model to have active and inactive records instead of deleting them permanently.
  • The HTTP verb PUT is used to “replace” (update) the content of an existing object with the provided content. If a collection URI is specified, the entire data should be replaced with the provided one, whereas an element URI(ID) would replace that specific element only.

Using the API

Important notes

  • HTTPS is required to use the Betty Blocks API. The API does not work on HTTP.
  • The base URL of all your API request will always be https://YOURAPP.bettyblocks.com/api  Every example given further on is appended on this base URL.
  • You can find the UUID of a filter/model/property/view by looking at your URL if you click on such an item in your app. A string will be added in your URL, which is the UUID. (For example: c5ad90ff1564ab78304f1bfc9b89ae2)
  • Use record[PROPERTYNAME]=VALUE  to assign values to properties.
  • The API actually uses the table names instead of the model names. The default table name is just the model name in plural (mostly just +s) but if you've changed the model name, the table name won't change, so it could be different. To see the table name, open the model with Advanced Options turned on.
  • Postman in desktop application, ideal for testing HTTP requests, thus for testing the Betty Blocks API. We've used Postman to show you how the API works (see screenshots below). We advise you to use Postman to test the API.

Example Requests

Every kind of request is accompanied by an example in Postman. Variables can be added in your URL after an ?. For example:  

https://yourapp.bettyblocks.com/api/users?limit=20

To combine multiple parameters in a request's URL, use & (ampersand). These are automatically added when the parameters are added by using body variables

Uppercased words in the examples are variables, meaning you should change this to real values according to your specific case.

GET REQUESTS

Get records from a model

https://YOURAPP.bettyblocks.com/api/models/TABLENAME/records

Get a specific record from a model by ID

/models/TABLENAME/records/ID

Filter the return by filter

/models/TABLENAME/records?filter_ids=UUID

Filter the return by view

/models/TABLENAME/records?view_id=UUID

Filter the return by view and filter

/models/TABLENAME/records?view_id=UUID&filter_ids=UUID

Return only the values from properties requested

/models/TABLENAME/records?property_ids[]=UUID

Can be used multiple times, as the [] indicates it accepts an array.
Example: /models/TABLENAM/records?property_ids[]=f696056064c24f4cacf2bc788363b568&property_ids[]=1ccadc86ac9c4fbfbd0762f59fe29716 

Use a limit on the records returned

/models/TABLENAME/records?limit=AMOUNT

The default limit is set to 100.

Use an offset on the records returned

/models/TABLENAME/records?offset=AMOUNT

Order the return by property

/models/TABLENAME/records?order=UUID:asc

or

/models/TABLENAME/records?order=UUID:desc

POST REQUESTS

Create a record in a model

/models/TABLENAME/records/new

To add records of a related model, you can add the ID's of the existing records to the body variables. For example when you create a new employee in existing companies:

Property: record[first_name]  >>> value
Property: record[last_name]  >>> value
Relation: record[companies]  >>> ID values (for example: 2,5 = 2 companies with ID 2 and 5 ) 

Create a public file (asset)

/assets

Use file as the request's payload. If the file is posted correctly, the response of the API will be a temporary asset identifier. Example:

"tmp:1562939263-28885-xxxx/image.jpeg"

This temporary identifier can be used to assign the file to a location within the application. This location can either be within a model or within the public files. The following URL should be used to post a file to the public files location.

/file_assets/new

This URL accepts 2 values in the request's payload: url and filename. The temporary identifier that was given in the previous response should be used as value for the url property. The value of the filename property will set a name for the file. If filename has no value, the name of the uploaded file will be set for the filename property. 

PUT REQUESTS

Update a record

/models/TABLENAME/records/ID

Include an ID of a record in the URL to collect a record of the used model. 

To add records of a related model, you can add the ID's of the existing records to the body variables. For example when you create a new employee in existing companies:

Property: record[first_name]  >>> value
Property: record[last_name]  >>> value
Relation: record[companies]  >>> ID values (for example: 2,5 = 2 companies with ID 2 and 5 ) 

DELETE REQUESTS

Delete a record

/models/TABLENAME/records/ID

Include an ID of a record in the URL to collect a record of the used model.  
The response will contain a 204 No Content status, as the requested record is deleted.

Actions

Triggering an action

/api/models/MODEL-UUID/actions/ACTION-UUID/execute

Every action can have a model. You'll need the UUID of that model and the UUID of the action to trigger it using the API.

Note: When you trigger an action via the API, var:record will not contain a value. If you want to execute the action on a record you'll need to give some input variable (i.e. the id of the record).

Triggering an action with input variables

/api/models/MODEL-UUID/actions/ACTION-UUID/execute?inputvar=value 

To include an input variable in your request, append the value behind the ? (questionmark) in the url, or pass them in the request's body.

Action's response: Background vs. foreground

The response received after requesting an action in your app, depends on wether the action is set to background or foreground processing. 

Background: The request triggers an action, which is scheduled for background processing. When the action will be processed, is not yet certain. The application won't wait before sending back a response, so you'll receive an empty body with statuscode 201 Created.
Foreground: The request triggers an action, which is scheduled for foreground processing. The action will be immediately picked up and the application will wait before sending back a response. This takes longer than with background processing, but does include the used variables and outcome of the action.
The request's body and statuscode depends on the outcome of the action.

HTTP status codes

You will receive HTTP status codes from the API informing you about what happened with your request. Below are the most common responses of the API.

200 OK

Standard response for successful HTTP requests. The actual response will depend on the request method used. In a GET request, the response will contain an entity corresponding to the requested resource. In a POST request the response will contain an entity describing or containing the result of the action.

201 Created

The request has been fulfilled and resulted in a new resource being created. You will get the created record in the return

204 No content

The request was successfully processed but the response has no value. This is a positive response when deleting a record.

400 Bad request

The request cannot be fulfilled due to bad syntax or missing data.

401 Unauthorized

The request cannot be fulfilled due to the lack of, or invalid, authorization.

404 Not found

The requested resource could not be found. It has probably been (re)moved or you've made an error in the URL.

502 Bad Gateway

The application could not fulfill your request, this is an error in the app most of the time. You should check the logs in the app for errors. If not, you probably trying something the app can't process. Check your request.

These HTTP status codes are a universal internet standard. If you'd like more info about status codes, you can search the web.

Troubleshooting

If you run into any problems, you've most likely made a minor syntax error somewhere. If not, check out all given examples for an example most like your own case. Make sure you've taken the important notes into consideration.

Still having trouble? We'd like to hear you struggles, so we can make sure you can continue developing and nobody else will encounter the same trouble in the future!

You're always free to start a topic on our Forum or get in touch with us directly via the chat logo at the bottom-right of your screen!

Did this answer your question?