Warning!
You’re now reading a legacy document. The features described below are only usable within the classic generation environment.
The Betty Blocks REST API will be deprecated in the future, we recommend using the Data API for new features.
With the Betty Blocks API, it’s possible to communicate with your application from another Betty Blocks application or an external application. This article will explain the possibilities of the API.
This article will explain:
How to access the API
How to use the API
Which HTTP requests can be used and how to use them
How to set up authentication
To be able to access the API an authentication needs to be set up. The Betty Blocks API is protected with HTTP basic authentication so without a proper authentication it will not be possible to create a connection.
To set up the authentication, an API user should be created. This can be done by granting an existing user API access or by creating a new user with a random (non-existing) email address to give the API access to. It is important to note that the rights of the user are inherited by the API, meaning that if the user cannot create, update or delete models this will also not be possible for the API. The API access can be given to a user within the user management settings of the app, these can be accessed by going to settings and selecting the user management tab. When on this page, access can be given to a user by clicking on the API button of a user. By doing this an API key will be generated and returned.
Beware! This API key is only shown once! Make sure to make a copy of this key because it is not possible to view it again.
Once the API has been generated, the authentication can be set up with HTTP Basic authentication. The username should be the API user’s email address, and the password should be the generated API key.
Keep in mind that if an API user is removed from the app all API calls authenticated with that user will stop working.
Using the API
When using the API there are a couple of things that are important to note:
It is required to use an HTTPS protocol when trying to reach the Betty Blocks API. The API will not respond on an HTTP protocol.
When reaching the API the following base URL should always be used:
https://YOURAPP.bettyblocks.com/api/
For some requests, the UUID (Universally Unique Identifier) is needed to identify where the API should connect to. When you are on the page of the filter/model/property/view, a string will be added to the URL. This is the UUID. Sometimes this UUID will have a hashtag prepended. This is not part of the UUID and shouldn't be used for the API. (For example: c5ad90ff156ab78304f1bfc9b89ae2)
When using input values for the API call the following notation should be used:
record[PROPERTYNAME]=VALUE
To access the data of a model, the table name should be used instead of the model name. The default table name is just the model name in plural, but changing the model name does not change the table name. In that case, the table name will be different from the model name. The table name can be found in the model settings when Advanced Options is turned on.
When testing the API we advise you to use an external tool like postman. With this tool, it is very simple to test API connections with your application. In the example images below we also use postman. To download postman you can go to this link: Get postman.
The Betty Blocks API uses different HTTP requests to perform different actions. A different URL is needed for every action. The examples below will explain which URL should be used for which action. The examples will be ordered under the HTTP request that should be used with the action. Each example should be appended after the base URL.
GET Requests
Get all records from a model
models/TABLE_NAME/records
Parameters can be added to this action after a question mark in the URL. With these parameters, you can alter the data that will be returned through the API. These are the parameters that can be appended to the get URL:
Filter_ids: This parameter makes it possible to use existing filters from an application on the API data. It is also possible to use multiple filters in one API call.
?filter_ids=FILTER_UUID
?filter_ids[]=FILTER_UUID&filter_ids[]=FILTERUUID
View_id: This parameter can be used to fetch data from a grid, the data that is returned looks different from the regular API data. Instead of column names, a UUID for each column is given. This is because the column name can differ from the actual property name. Also, a new property is returned, busy. This property shows whether the property was being reloaded at the time of the API call.
?view_id=VIEW_UUID
Limit: This parameter sets a limitation on the number of objects that the API call will return. The limit is set to 100 by default.
?limit=AMOUNT
Order: This parameter will order the API data on a property in ascending or descending order.
?order=PROPERTY_UUID:asc
?order=PROPERTY_UUID:desc
Property_ids: This parameter makes the API call only return the data of the set properties, together with the corresponding id of the object.
?property_ids=PROPERTY_UUID
?property_ids[]=PROPERTY_UUID&property_ids[]=PROPERTY_UUID
These parameters can be combined by placing an ampersand (&) between them. This way it’s possible to use multiple parameters in one API call to get exactly the data that is necessary.
Get a specific record from a model
models/TABLE_NAME/records/ID
POST Requests
Create a new record in a model
models/TABLE_NAME/records/new
The values of properties can be appended to the URL after a question mark. This should be done in the standard notation. When using multiple values these can be separated with an ampersand. It is possible to create a connection with a connected model by using the id of the existing records to the property that should connect with the model.
?record[PROPERTY]=VALUE
The API will return an error if a property has the validate presence setting turned on but it doesn’t get a value. When the object is created successfully the API will return the created object.
Post a file
assets
When posting a file property file should always be used as value for the record name of the posted property. If this is not the case, the API will respond with a 502 error. If the file is posted correctly then the response of the API will be a temporary URL file. This temporary URL 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 properties as a parameter: url and filename. The temporary URL 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.
Trigger an action
models/MODEL_UUID/actions/ACTION_UUID/execute
When executing an action that requires input variables, these can be appended to the URL after a question mark. For input variables no special notation is necessary. If the triggered action should be executed on a specific record then the id of that record should be passed as an input variable.
?VARIABLE_NAME=VALUE
If the API returns an empty body then the action is executed successfully.
PUT Requests
Update a record
models/TABLE_NAME/records/ID
The values of properties can be appended to the URL after a question mark, this should be done in the standard notation. When using multiple values these can be separated with an ampersand. If a property has no value then the old value will not change.
?record[PROPERTY]=VALUE
DELETE Requests
Delete a record
models/TABLE_NAME/records/ID
If the object is deleted successfully the API will respond with an empty body.
HTTP status codes
The API will return a status code with every response, these status codes will indicate what happened during the 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 return.
204 No content
The request was successfully processed but the response has no value. This is a good 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 there is an error in the URL.
502 Bad gateway
The application could not fulfill the request, this is an error in the app most of the time. Errors could appear in the application logs. If not, the issue is probably trying something that the app can’t process. Check the request.
These HTTP status codes are a universal internet standard. For more information about status codes, you can take a look at this website: List of HTTP status codes